Guide for creating custom presets - PyPty (python + ptychography)

PyPty Parameters for Creating Custom Presets

In PyPty, all functions operate using a dictionary that defines your reconstruction setup. This dictionary is typically named pypty_params.

The core function for running iterative ptychographic reconstruction is pypty.iterative.run(), which accepts pypty_params as its single argument.

For simple setups, we recommend using the pypty.initialize module, which helps generate common parameters and arrays automatically. However, for more complex or custom experiments, this guide explains how to construct your own pypty_params dictionary manually.

Lambda-Type Parameters in PyPty

Before diving into parameter details, it's important to understand a special type of input PyPty supports: lambda-type parameters.

Because PyPty is iterative, some parameters can be adjusted depending on the current epoch. To do this, use a lambda function that takes the current epoch number as input and returns a value dynamically.

Example

To apply the smart_memory flag only every 10 epochs, set it like this:

smart_memory: lambda x: x % 10 == 0;

The parameters that can be written in this way are marked as pypty_lambda type in the Default Data Type column. They can also be specified as a sting containing the code, e.g. 

smart_memory: "lambda x: x % 10 == 0";

⚠️ Important Note on Lambda Usage
We do not recommend toggling constraints or critical parameters every few epochs. Doing so can interfere with PyPty’s BFGS optimizer, which builds a Hessian matrix based on parameter continuity. Sudden changes can disrupt convergence and lead to suboptimal results.

Instead, design lambda functions so that once a parameter is activated, it remains consistently enabled for the rest of the reconstruction. This ensures smooth optimization behavior and compatibility with the underlying solver.

For example, to enable a parameter starting at epoch 20 and keep it active afterward:

"atv_weight": lambda x: 1e-3*(x >= 20)
This pattern is ideal for turning on advanced features or constraints after an initialization period without destabilizing the optimization.

Full list of paramerers for pypty.iterative.run()

Backend Settings

Parameter Default Value Default Data Type Description
backend cp NumPy-like python module Currently not used, but will be a feature in the future. Right now, whenever CuPy is available, it is used as the GPU backend. If no CUDA is detected, NumPy is used as a CPU replacement. We plan to add support for Apple Silicon, but we are waiting for an optimal library to appear.
default_dtype "double" str Default data type for computations. Another option is "single".

Dataset

Parameter Default Value Default Data Type Description
data_path "" str Path to the dataset. It can be an .h5 file with a dataset named "data" containing a 3D measurement array (N_measurements, y, x). Another option is a 4D .npy array or a 3D .npy array.
dataset None numpy-array or None If you don't want to store data on disk, you can attach a numpy-array with your data to the parameters. If it's provided, data_path is ignored.
masks None numpy.ndarray or None Masks (virtual detectors) used for data compression. For uncompressed data, leave it as None.
data_multiplier 1 float Multiplier for data values. Used to rescale patterns on the fly without modifying the stored dataset. All patterns will be multiplied by this number.
data_pad 0 int Padding applied to data. Use it to pad patterns on the fly without modifying the stored dataset. We recommend setting it to 1/4 of the pattern width for optimal sampling conditions in far-field mode.
data_bin 1 int Binning factor for data. Used to bin patterns on the fly without modifying the stored dataset. All patterns will be binned by this number.
flip_ky False bool Flag indicating that one has to flip ky. Useful if patterns are flipped and you don’t want to modify the stored dataset. Another option is to create a PyPty-style .h5 dataset.
data_shift_vector [0,0] list Shift vector (list with two-values) applied to measurements. Used to shift patterns on the fly without modifying the stored dataset. All patterns will be shifted by the specified number of pixels.
upsample_pattern 1 int Upsampling factor. If the beam footprint is larger than the extent (in far-field mode), this allows to artificially upsample the beam in reciprocal space. Experimental feature! Windowing constraints may be required.
sequence None list or None or pypty_lambda Sequence used in data processing. This is a list indicating the measurements that will be used for iterative refinement. If None, all measurements contribute. This parameter is useful for reconstructions on subscans without creating additional data files.
use_full_FOV True bool Boolean flag. Only useful if a sequence is provided. If True, the object can accommodate all measurements. If False, the object accommodates only selected measurements.

Saving and Printing

Parameter Default Value Default Data Type Description
output_folder "" str Path to the folder where output files will be saved.
save_loss_log True bool Boolean flag. If True, the loss log will be saved as loss.csv.
epoch_prev 0 int Previous epoch count. Useful for restarting a reconstruction.
save_checkpoints_every_epoch False bool or int Save checkpoints every epoch. If True, checkpoints will be always saved, if it is provided as an integer, checkpoints will be saved every n'th epoch.
save_inter_checkpoints True bool or int Save intermediate overwritable checkpoints. This will create .npy arrays: co.npy for the object, cp.npy for the probe, cg.npy for the scan grid, ct.npy for the tilts, cs.npy for the static background, and cb.npy for the beam current. If True, checkpoints will be always saved, if it is provided as an integer, checkpoints will be saved every n'th epoch.
print_flag 3 int Print verbosity level: 0 for no printing, 1 for one overwritable line, 2 and 3 for moderate output. 4 gives the most detailed output.

Experimental Parameters

Parameter Default Value Default Data Type Description
acc_voltage 60 float Acceleration voltage in kV.
aperture_mask None numpy.ndarray or None Mask for the aperture. Can be used for reciprocal probe constaint later (see section constraints).
recon_type "far_field" str Type of reconstruction. Options: "far_field" or "near_field".
alpha_near_field 0.0 float Alpha parameter for near-field reconstruction & flux preservation.
defocus_array np.array([0.0]) numpy.ndarray Array of defocus values for near-field measurement. Irrelevant for far-field. It can contain either a single common defocus value for all measurements or individual values for each measurement. Units: Angstroms.
Cs 0.0 float Spherical aberration coefficient. Units: Angstroms.

Spatial Calibration

Parameter Default Value Default Data Type Description
slice_distances np.array([10.0]) numpy.ndarray Distances between object slices. Units: Angstroms. You can specify a single value common for all slices or provide individual values.
pixel_size_x_A 1.0 float Pixel size in the x-direction (Angstroms).
pixel_size_y_A 1.0 float Pixel size in the y-direction (Angstroms).
scan_size None tuple or None Tuple describing the number of scan points in y- and x- directions. Required for constraining positions and tilts.
num_slices 1 int Number of slices in the object.

Refinable Arrays

Parameter Default Value Default Data Type Description
obj np.ones((1, 1, num_slices, 1)) numpy.ndarray Initial guess for the transmission function to be retrieved. Shape: (y, x, z, modes). If the y and x dimensions are insufficient for the scan grid, the object will be padded with ones.
probe None numpy.ndarray or None Real-space probe. Shape: (y, x, modes). For advanced experiments, the probe can be 4D (y, x, modes, subscans). If None, PyPty will automatically initialize the beam from the dataset.
positions np.array([[0.0, 0.0]]) numpy.ndarray Scan positions in pixels of the reconstruction. Shape: [N_measurements, 2], formatted as [[y0, x0], [y1, x1], ..., [yn, xn]]. Single-shot experiments can define one common scan point, e.g., [[0,0]].
tilts np.array([[0.0, 0.0, 0.0, 0.0, 0.0, 0.0]]) numpy.ndarray Tilt angles in real and reciprocal spaces. There are 3 types of tilts in PyPty framework: before, inside and after. First one is a beam tilt before the specimen, i.e. a shift in aperture plane. Second type is a tilt inside of a specimen, i.e. after each slice the beam is shifted in real space. Third type is a post-specimen tilt i.e. a shift in a detector plane. All three types of shifts are contained in this tilt array. Shape: [N_measurements, 6]. Format: [[y0_before, x0_before, y0_inside, x0_inside, y0_after, x0_after], ..., [yN, xN]]. Single-shot experiments can define one common tilt (with shape [1, 6]).
tilt_mode 0 int Mode for applying tilts: 0, 3, 4 for inside, 2, 4 for before, and 1, 3, 4 for after the specimen.
static_background 0 numpy.ndarray or float Static background intensity. Shape should match initial patterns but padded by data_pad//upsample_pattern. Use 0 for no static offset. If provided as postive float, the algorithm will initialize the backgrund with a proper shape on its own.
beam_current None numpy.ndarray or None Accounts for different currents (or exposure times) during measurements. If provided, must be a 1D array with length matching N_measurements.

Propagation, Shifting, and Resizing

Parameter Default Value Default Data Type Description
propmethod "multislice" str Wave propagation method. Options: "multislice", "better_multislice", and "yoshida". The last two are higher precision but slower.
allow_subPixel_shift True bool Allow subpixel shifts. If False, positions will be rounded to integers until refined.
dynamically_resize_yx_object False bool or int or pypty_lambda If position updates become too large, the object will be padded to accommodate the new scan grid. If set to a positive integer, resizing occurs when position updates exceed this value.
extra_space_on_side_px 0 int Extra space added around the object in pixels.

Bandwidth Limitation

Parameter Default Value Default Data Type Description
damping_cutoff_multislice 2/3 float Frequency cutoff for multislice beam propagation. Values larger than 2/3 can cause aliasing artifacts. Recommended ≤ 2/3.
smooth_rolloff 0 float Rolloff parameter for smooth frequency cutoffs.
update_extra_cut 0.005 float Extra frequency cutoff for the full object. Ensures bandwidth limitation beyond the cropped ROIs of the multislice object.
lazy_clean False bool If True, the full transmission function will not be bandwidth-limited (only cropped ROIs will be). Recommended: False.

Optimization Settings

Parameter Default Value Default Data Type Description
algorithm "lsq_sqrt" str Error metric for reconstruction comparison. Options: "lsq_sqrt" (Gaussian), "ml" (Poisson), "lsq" (classic summed squared error), and "lsq_sqrt_2" (modified Gaussian). If data is compressed via virtual detectors, the only option is "lsq_compressed" (summed squared error between signals).
epoch_max 200 int Maximum number of epochs (iterations).
wolfe_c1_constant 0.1 float or pypty_lambda Wolfe condition parameter (C1). Prevents update steps from being too large. Must be > 0 and < C2. Larger values enforce shorter step size.
wolfe_c2_constant 0.9 float or pypty_lambda Wolfe condition parameter (C2). Prevents update steps from being too small. Must be > C1 but < 1. Larger values allow larger steps.
loss_weight 1 float or pypty_lambda Weight applied to the loss function.
max_count 20 int or None Maximum number of forward-backward propagations per line search iteration. If exceeded, the update is rejected and history is reset. Use None or np.inf to disable.
reduce_factor 0.1 float Factor for reducing step size when the first Wolfe condition is not met.
optimism 3.0 float Factor for increasing step size when the second Wolfe condition is not met. To prevenet algorithm from going back and forth during linesearch, multiplication of optimism and reduce_factor (or of any powers of them) should not be equal to 1.
min_step 1e-20 float Minimum step size. If the step falls below this value, the algorithm resets history. Use 0 to disable.
hist_length 10 int or np.inf or pypty_lambda BFGS optimization history length. Values: 0 (Gradient Descent), 1 (Conjugate Gradient), N>1 (Limited-memory BFGS), np.inf (Full BFGS).
update_step_bfgs 1 float or pypty_lambda Common step applied to all refinable quantities. By default, after the first iteration, a Barzilai-Borwein method is used to inistialize the inverse Hessian, so most of the time, an update step of 1 should be accepted. Only during the very first iteration the linesearch might take some time to find an appropriate step.
phase_only_obj False bool or pypty_lambda Whether to consider the object as phase-only.
tune_only_probe_phase False bool or pypty_lambda Optimize only the reciprocal-space phase (CTF) of the probe.
tune_only_probe_abs False bool or pypty_lambda Optimize only the reciprocal-space amplitude (aperture) of the probe.
reset_history_flag False bool or pypty_lambda Flag to reset optimization history. See section "lambda-types" in this document. If provided, history will be manually resetted.

Updating Refinable Arrays

Parameter Default Value Default Data Type Description
update_probe 1 bool or pypty_lambda Whether to update the probe (1 for yes, 0 for no).
update_obj 1 bool or pypty_lambda Whether to update the object (1 for yes, 0 for no).
update_probe_pos 0 bool or pypty_lambda Whether to update probe positions (1 for yes, 0 for no).
update_tilts 0 bool or pypty_lambda Whether to update tilt angles (1 for yes, 0 for no).
update_beam_current 0 bool or pypty_lambda Whether to update beam current (1 for yes, 0 for no).
update_aberrations_array 0 bool or pypty_lambda Whether to update aberration array (1 for yes, 0 for no).
update_static_background 0 bool or pypty_lambda Whether to update static background (1 for yes, 0 for no).

Multiple Illumination Functions

Parameter Default Value Default Data Type Description
aberrations_array np.array([[0.0]]) numpy.ndarray Array of aberration values for multiple beams. Useful for large fields of view where the beam changes. Shape: [N_subscans, N_aberrations].
phase_plate_in_h5 None str or None Path to an HDF5 file containing phase plates for different measurements. Dataset name should be "configs". Shape: [N_measurements, Y_probe, X_probe].
aberration_marker None numpy.ndarray or None Marker for multiple CTFs. Should be a 1D array of length N_measurements, where each entry corresponds to a CTF index in aberrations_array.
probe_marker None numpy.ndarray or None Marker for probe variations. If provided, the probe should have shape [y, x, modes, N_subscans], and this array should contain indices specifying which probe to use for each measurement.

Memory Usage

Parameter Default Value Default Data Type Description
load_one_by_one True bool If True, data is loaded dynamically to save GPU memory. If False, all data is loaded at once (faster but memory-intensive).
smart_memory True bool or pypty_lambda If True, memory is managed intelligently, clearing cache when necessary to prevent memory fragmentation.
remove_fft_cache False bool If True, FFT cache is removed periodically to save memory. (Experimental feature)
compute_batch "auto" int or str Batch size for multislice computation. Default value "auto" will automatically estimate a value that would fit into your memory, but ideally one should balance it by hand for a particular GPU. Increasing this can speed up reconstruction but requires more GPU memory. Super large values are also useless as at some point you will reash the limit the compute capability.
force_dataset_dtype default_float_cpu numpy.dtype Forces the dataset to be stored in a specified data type. Can help reduce memory usage at the cost of precision.
preload_to_cpu False bool If True, preloads data to CPU before transferring it to GPU, improving transfer speeds for .h5 datasets.
force_pad False bool If True, pads data at the start of reconstruction (uses more memory but speeds up computation). If False, padding is applied on the fly to save memory.
memory_saturation 0.7 float If compute batch is set to "auto", this ratio will be used to estimate a compute batch that would requiere memory_saturation of the avalible GPU memory. If compute_batch is integer, memory_saturation is ignored.

Constraints Contributing to the Loss

Parameter Default Value Default Data Type Description
mixed_variance_weight 0 float or pypty_lambda Regularization weight that prevents low-frequency variations between object states.
mixed_variance_sigma 0.5 float or pypty_lambda Controls the spatial frequency range affected by mixed_variance_weight.
probe_constraint_mask None numpy.ndarray or None Mask for probe constraint in reciprocal space. Masked pixels are regularized using L2 norm.
probe_reg_constraint_weight 0 float L2 regularization weight for the probe in reciprocal space.
window_weight 0 float or pypty_lambda L2 regularization weight for the probe in real space.
window None numpy.ndarray or None or or pypty_lambda Window function used to constrain the probe in real space. Masked pixels are damped using L2 regularization. It can be either a 2d- real valued array with the same shape as upsampled and padded beam or a list containing two values: inner radius (fraction) and outer radius (fraction). Fractions will be multiplied with half of the probe width, everything inside of window will be kept intact, everything outside will be zeroed and intermediate values will be slighly damped.
abs_norm_weight 0 float L1 regularization weight applied to the absorptive potential (negative log of the transmission function’s absolute value).
phase_norm_weight 0 float or pypty_lambda L1 regularization weight applied to the phase of the object.
atv_weight 0 float or pypty_lambda Weight for Adaptive Total Variation (ATV) regularization on the transmission function.
atv_q 1 float or pypty_lambda ATV q parameter (controls the strength of smoothing). Recommended: 1.
atv_p 2 float or pypty_lambda ATV p parameter (1 = L1-like regularization, 2 = L2-like smoothing). Recommended: 2.
fast_axis_reg_weight_positions 0 float or pypty_lambda Regularization weight for fast-axis scan positions. Reduces the acceleration along one line.
slow_axis_reg_weight_positions 0 float or pypty_lambda Regularization weight for slow-axis scan positions. Reduces the acceleration along one column.
fast_axis_reg_weight_tilts 0 float or pypty_lambda Regularization weight for fast-axis tilts. Reduces the acceleration along one line.
slow_axis_reg_weight_tilts 0 float or pypty_lambda Regularization weight for slow-axis tilts. Reduces the acceleration along one column.
deformation_reg_weight_positions 0 float or pypty_lambda Regularization weight for enfourcing a regular (but deformed) scan grid.
deformation_reg_weight_tilts 0 float or pypty_lambda Regularization weight for enfourcing a regular (but deformed) tilts grid.

Constraints That Modify the Object and Probe 'By Hand'

Warning: These constraints reset the BFGS history when applied.

Parameter Default Value Default Data Type Description
apply_gaussian_filter False bool or pypty_lambda Applies a Gaussian filter to the phase of the object.
apply_gaussian_filter_amplitude False bool or pypty_lambda Applies a Gaussian filter to the amplitude of the object.
beta_wedge 0 float or pypty_lambda Removes high kz frequencies for low kx and ky in 3D object FFTs.
keep_probe_states_orthogonal False bool or pypty_lambda Enforces orthogonality of probe modes.
do_charge_flip False bool Performs charge flipping on the object.
cf_delta_phase 0.1 float Delta phase for charge flipping.
cf_delta_abs 0.01 float Delta amplitude for charge flipping.
do_charge_flip False bool or pypty_lambda Perform charge flipping on the object.
cf_delta_phase 0.1 float or pypty_lambda Delta phase for charge flipping.
cf_delta_abs 0.01 float or pypty_lambda Delta amplitude for charge flipping.
cf_beta_phase -0.95 float or pypty_lambda Beta phase parameter for charge flipping.
cf_beta_abs -0.95 float or pypty_lambda Beta amplitude parameter for charge flipping.
fancy_sigma None None or float oor pypty_lambda Custom sigma parameter to enforce atomicity.
restart_from_vacuum False bool or pypty_lambda Resets the object to 1 while keeping other parameters unchanged. See section "lambda-types" in this document.
reset_positions False bool or pypty_lambda Resets the positions to initial guess while keeping other parameters unchanged. See section "lambda-types" in this document.

Beam Initialization

Parameter Default Value Default Data Type Description
n_hermite_probe_modes None tuple or None Number of Hermite probe modes. A tuple [nx, ny] specifying mode orders in x and y directions. If None, no Hermite modes are applied.
defocus_spread_modes None numpy.ndarray or None 1D array with different defocus values for initializing probe modes. Useful for simulating defocus spread in the beam.
aberrations None numpy.ndarray or None 1D array of aberration coefficients in Krivanek notation, e.g., C10, C12a, C12b, C21a, C21b, C23a, C23b, C30. Units: Angstroms.
extra_probe_defocus 0 float Extra probe defocus applied in Angstroms. Useful for adjusting initial beam focus in multislice reconstructions.
estimate_aperture_based_on_binary 0 float If > 0, the aperture is estimated based on a binary threshold. Pixels in the data larger than mean(data) * estimate_aperture_based_on_binary are considered part of the aperture.
beam_ctf None numpy.ndarray or None Beam Contrast Transfer Function (CTF). If provided, must be a 2D NumPy array with dimensions matching the upsampled probe size.
mean_pattern None numpy.ndarray or None Mean diffraction pattern used for probe initialization. If provided, the probe is created using an inverse Fourier transform of this pattern.

Examples for iterative ptychography - PyPty (python + ptychography)

Breakdown of Examples for Iterative Ptychography

This section provides a detailed breakdown of an iterative ptychography reconstruction using PyPty. To get started, create a Python script and import the necessary libraries:

import numpy as np
import pypty
# NumPy is used for minor preprocessing, while all major operations are handled by PyPty.
print("PyPty version: ", pypty._version_)
We will need numpy to do some small preprocessing outside of pypty, but the major steps will be done with pypty functions.

Normal 4D-STEM iterative ptychography.

In this section I will go through the steps required to do a ptychographic reconstruction from normal 4D-STEM data (far-field).

Creation of Calibrated Data

In a first step we want to create and center a 4D-STEM dataset (in h5 format). PyPty can also accept raw numpy-arrays, but it's better to do this preprocessing step. 

path = path_to_your_data
name = name of your dataset
path_raw = path+name+".npy"
path_h5  = path+name+".h5"

pypty.initialize.create_pypty_data(path_raw, path_h5, swap_axes=False,
                    flip_ky=0,flip_kx=0, comcalc_len=200*200,
                    comx=0, comy=0, bin=1, crop_left=None,
                    crop_right=None, crop_top=None, crop_bottom=None, normalize=False, exist_ok=1)

Experimental parameters

PyPty accepts .json metadata from Nion microscopes, but you can also specify all entries yourself. Here I create a dictionary experimental_params with relevant parameters. See the experiment description for further details.

path_json="" ## I will leave this string like this and specify everything by hand.
output_folder=your_output_folder

experimental_params={
    'output_folder': output_folder,
    'path_json': path_json, 
    'data_path': path_h5,
    
    ### You can specify one of the following three parameters
    'rez_pixel_size_A': None,
    'rez_pixel_size_mrad': None,
    'conv_semiangle_mrad': 33.8,
    
    
    'scan_size': [256,256], ## this is number of scan points along slow and fast axes
    
    ###  You can specify one of the following two parameters
    'scan_step_A': 0.18, # scan step in Angstrom
    'fov_nm': None,
    
    'acc_voltage': 60, ## kV

    'aberrations': [200,0,0],## Angstrom  [C10, C12a, C12b], can be longer
    
    'PLRotation_deg': 4.65, # deg
    
    
    'bright_threshold': 0.2, ## this parameter will be used to estimate the aperture
    
    'total_thickness': 6, ## Angstrom, thickness of the sample
    'num_slices': 1,  ## number of slices in your reconstruction
    
    'plot': True, ## pypty will plot a few things
    'print_flag': 3, ## max verbosity
    'data_pad': None, ## None will add 1/4 of pixels to each side. This is done to prevent aliasing. You can do any other positive int.
    
    ## now there are 2 nexus tags you can specify. This will help to identify your reconstruction in the Future.
    'chemical_formula': YOUR_Formula, 
    'sample_name': NAME_of_YOUR_Sample,
    
    }

Loading a reconstruction preset

Parameters for iterative ptychography are stored in a dictionary typically named pypty_params.

1) Such presets are typically stored as .pkl data and you can load them via a function in utils module

path_to_your_pkl_preset=
pypty_params=pypty.utils.load_preset(path_to_your_pkl_preset)

2) Alternatively, you can load them from a nexus data of another reconstruction

path_to_your_nxs_preset=
pypty_params=pypty.utils.load_nexus_params(path_to_your_nxs_preset)
3) A third option is to construct your custom preset as a dictionary from scratch (Please see the guide )

pypty_params={
    "your_entry": something,
    ...
    }
4) Finally, you can specify it as None, then you will have a standard preset

pypty_params=None

Joining a preset with experimental parameters

Once you have a preset, you can add experimental data to it.

pypty_params=pypty.initialize.append_exp_params(experimental_params, pypty_params)

Starting Ptychography

This is done with a single function and single argument, pypty_params:

pypty.iterative.run(pypty_params)

Saving your Results as one Nexus file

Once your reconstruction is done, you will find a bunch of files in the output_folder. You can stack them into one big nexus file via a single function. You can also select where the .nxs file will be saved via path_to_your_nexus_file

pypty.utils.convert_to_nxs(output_folder, path_to_your_nexus_file)

Reconstruction without an extra h5 file

If you do not want to create an extra .h5 file (not recommended), you can specify the 4D-STEM data directly in the experimental parameters (before you join them with pypty_params). 

experimental_params["dataset"]=dataset
Note than in this case the entry data_path will be ignored and you can leave this field empty. The dataset itself can be either 4D or 3D (with 2 scan axes merged into one).

Iterative Ptychography from Virtual Detectors

If you want to perform a reconstruction from data compressed by virtual detectors, you first have to ensure that the array of detectors has shape [N_detectors, k_Y, k_X] and your data has shape [Scan_Y, Scan_X, N_detectors]. Then you attach these two arrays to experimental parameters.

experimental_params={
    "dataset": compressed_data,
    "masks": virtual_detector_array,
    
    
    ###  In this case you must specify one of the following two parameters
    'rez_pixel_size_A': None,
    'rez_pixel_size_mrad': 1,
    
   # ... Rest of your parameters.
}
Also, you may want to update your reconstruction settings. For Compressed data PyPty has following objective function types:

Objective_name Description
lsq_compressed Least-squared fit
gauss_compressed Gaussian noise model
poisson_compressed Poissonian noise model

Then you must specify algorithm as one of these three options in pypty_params: 

pypty_params={
        "algorithm":  gauss_compressed, 
        #... Rest of your parameters
        }
Then you can launch ptychography with the same pypty.iterative.run function.

Notebook / example pipeline - PyPty (python + ptychography)

Examples for direct methods - PyPty (python + ptychography)

Examples for direct methods

This page presents example usage of PyPty’s direct reconstruction methods: Differential Phase Contrast (DPC), Tilt-Corrected Bright Field (tcBF), and Wigner Distribution Deconvolution (WDD). These methods are used when a direct (non-iterative) reconstruction is preferred or as preprocessing for iterative methods.

Differential Phase Contrast (DPC)

PyPty is supplied with two functions for differential phase contrast. Both of them aim so solve a Poisson equation, i.e. to reconstruct a phase from its laplacian, gradient of the COM vector field. The first method, based on the Fast Fourier Transform (FFT), reconstructs the phase efficiently and can be executed as follows (including visualization using matplotlib)

dpc_phase, pypty_params= pypty.dpc.fft_based_dpc(pypty_params, hpass=1e-1, lpass=0)

plt.imshow(dpc_phase, cmap="gray")
plt.title("DPC Phase (FFT-based)")
plt.colorbar()
plt.show()
Note that fft-based DPC returns both phase and parameter dictionary as it stores the calculated COM vector field (and the angle between real and reciprocal spaces). If these two quantities are not in pypty_params, it attempts to automatically calculate them.

Second method is iterative and accounts for non-periodic boundary conditions:

dpc_phase=pypty.dpc.iterative_dpc(pypty_params, num_iterations=100, beta=0.5, hpass=1e-1, lpass=0, step_size=0.1)
plt.imshow(dpc_phase, cmap="gray")
plt.title("DPC Phase (iterative)")
plt.colorbar()
plt.show()

Please see the module description for detailed description of the parameters.

Tilt-Corrected Bright Field (tcBF)

In PyPty framework tcBF is done in two steps. First one aims to fit the aberrations of the beam and rotation angle between real and reciprocal spaces by creating an unupsampled tcBF image via run_tcbf_alignment:

pypty_params=pypty.tcbf.run_tcbf_alignment(
        pypty_params,
        binning_for_fit=np.tile([5], 30), 
        optimize_angle=True,

        cross_corr_type="abs",
        refine_box_dim=5,
        upsample=10,
        cancel_large_shifts=0.9,
        reference_type="bf",
        tol_ctf=1e-8
        )

Note that you have to play with binning values and cross-correlation parameters to get an optimal result. Also, fitted rotation angle typically has a +- pi ambiguity, so if your defocus value comes out with a sign different from the experiment, I suggest to rerun the reconstruction.

A second tcBF function assumes that you already did an alignment and performs an upsampled reconstruction:

tcbf_image,tcbf_px_size = pypty.tcbf.upsampled_tcbf(pypty_params, upsample=3,
                                    pad=10, default_float=32,round_shifts=True)
                                    
plt.imshow(tcbf_image,  cmap="gray")
plt.title("tcBF image (x3 upsampling)")
plt.colorbar()
plt.show()

Wigner Distribution Deconvolution (WDD)

The last direct reconstruction method is Wigner distribution deconvolution (WDD). It is a direct method that reconstructs the object's complex wavefunction by deconvolving the measured intensity distribution with the known probe. WDD requires a calibrated pypty_paramsdictionary containing rotation angle, scan steps and a complex beam (or a set of aberrations). A simple usage example is

obj_wdd=pypty.direct.wdd(pypty_params,  eps_wiener=1e-3)

plt.imshow(np.angle(obj_wdd), cmap="gray")
plt.title("WDD Phase")
plt.colorbar()
plt.show()
The parameter eps_wiener serves as a regularization term (high-pass filter) to stabilize the deconvolution, preventing division by zero.

Using Direct Methods for Initial Guesses

pypty.initialize module is supplied with a function get_ptycho_obj_from_scan that can be used to create complex transmission function based on a measurement sampled at the scan points, this can be a DPC or WDD phase. Usage example is:

pypty_params =  pypty.initialize.get_ptycho_obj_from_scan(pypty_params, array_phase=dpc_phase, array_abs=None)

If you have an array on a grid with finer sampling than the actual scan grid of your reconstruction, you may first create an upsampled grid in the image coordinates and use the array for initial guess like this:

image = ## your upsampled image
image_pixel_size = ## pixel size of your image
left_zero_of_scan_grid = # how many pixels of the image are from left of the scan
top_zero_of_scan_grid  = # how many pixels of the image are from top of the scan
scan_array_A=pypty.initialize.get_grid_for_upsampled_image(pypty_params, image, image_pixel_size=image_pixel_size, left_zero_of_scan_grid=left_zero_of_scan_grid, top_zero_of_scan_grid=top_zero_of_scan_grid)

pypty_params =  pypty.initialize.get_ptycho_obj_from_scan(pypty_params, array_phase=image, array_abs=None, scan_array_A=scan_array_A)

You can also manually specify the initial guess by providing keys like "obj", "probe" or "positions", for more see Guide for creating custom presets.

These direct methods are essential tools in PyPty for rapid insight and as a starting point for more advanced reconstructions. You can combine them with iterative pipelines by injecting results into the initialization phase.

Description of the experiment - PyPty (python + ptychography)

Getting started with the initialize Module

PyPty comes with an initialize module (see the API Reference), which is designed specifically for far-field ptychography.

This module makes it easy to:

  • Create a calibrated dataset
  • Generate a PyPty preset from scratch

If your experimental setup involves additional complexity or non-standard conditions, please refer to the Custom Preset Guide for more flexible configuration.

However, if your setup fits the typical far-field ptychography case, you can summarize all key experimental parameters in a single Python dictionary. For clarity, we usually refer to this as experimental_params.

The dictionary should contain the following keys:

Essential Data Paths

Key Type Description
data_path str Path to a 3D PyPty .h5 dataset ([N_measurements, ky, kx]) or a 4D-STEM .npy dataset.
masks ndarray or None If the data is compressed, provide the virtual detectors ([N_masks, ky, kx]).
output_folder str Directory where results will be stored.
path_json str Path to a Nion-style .json file with metadata (optional).

Electron Beam Properties

Key Type Description
acc_voltage float Accelerating voltage (in kV).
rez_pixel_size_A float Reciprocal pixel size (in Å⁻¹).
rez_pixel_size_mrad float Reciprocal pixel size (in mrad).
conv_semiangle_mrad float Beam convergence semi-angle (in mrad).
aperture ndarray (optional) Binary 2D mask representing the aperture.
bright_threshold float Threshold for estimating an aperture. Everything above threshold * max(PACBED) is considered bright field.

Scan and Positioning

Key Type Description
scan_size tuple(int, int) Number of scan points along slow (y) and fast (x) axes.
scan_step_A float Scan step (STEM pixel size) in Å.
fov_nm float Field of view (FOV) along the fast axis in nm.
special_positions_A ndarray (optional) If data was acquired on a non-rectangular grid, specify positions as [y_0, x_0], ..., [y_n, x_n] (in Å).
transform_axis_matrix ndarray (2×2) Transformation matrix for position correction.
PLRotation_deg float or "auto" Rotation angle between scan and detector axes. If "auto", an iDPC measurement estimates this angle.

Reconstruction Settings

Key Type Description
num_slices int Number of slices used for multislice propagation (default: 1).
total_thickness float Total thickness of the sample (in Å).
data_pad int or None Reciprocal space padding. Default: 1/4 of pattern width.
upsample_pattern int Upsampling factor for diffraction patterns.
flip_ky bool Flip the y-axis of diffraction patterns.
defocus float Extra probe defocus (besides aberrations).
aberrations list or ndarray Beam aberrations (stored in Krivanek notation).

Output & Debugging

Key Type Description
plot bool If True, generates plots of key experimental parameters.
print_flag int Controls verbosity (0 = silent, 1 = summary, 2+ = detailed logs).
save_preprocessing_files bool If True, saves intermediate preprocessing files.

Nexus Tags

Key Type Description
chemical_fomula string You can optionally provide a formula for your sample. PyPty will store this information.
sample_name string You can optionally provide a name of your sample. PyPty will store this information.

PyPty (python + ptychography)

Overview

PyPty is a phase retrieval library for near-field and far-field imaging in TEM/STEM. It supports:

  • Iterative ptychography
  • Direct ptychography (Wigner Distribution Deconvolution)
  • Differential phase contrast (DPC)
  • Tilt-corrected bright field (tcBF)
  • Focal series reconstructions
  • LARBED reconstructions

Developed by Anton Gladyshev (AG SEM, Physics Department, Humboldt-Universität zu Berlin).

Installation

To create a suitable Python environment for PyPty, you can use conda, mamba, or micromamba. Below are installation instructions using conda.

GPU Installation

git clone git@github.com:Anton-Gladyshev/pypty.git
cd pypty
conda env create -f pypty_gpu.yml
conda activate pypty
pip install .[gpu]

CPU Installation

git clone git@github.com:Anton-Gladyshev/pypty.git
cd pypty
conda env create -f pypty_cpu.yml
conda activate pypty
pip install .

About this Code

Main Purpose

The primary function of PyPty is gradient-based phase reconstruction from far-field intensities. This is handled via pypty.iterative.run(). Most other functions are designed to simplify usage of this core function.

A complete list of required arguments for pypty.iterative.run() is available in the custom presets guide.

Logic

Most PyPty functions accept a single input dictionary called pypty_params, which typically includes both experimental and reconstruction settings. These experimental parameters are often defined separately in a dictionary called experimental_params (see experiment description).

Once you’ve created a valid pypty_params for one experiment, you can reuse it for others by simply "attaching" new experimental parameters.

PyPty also supports various direct methods and tools for initialization.

Input Format

PyPty primarily operates on .h5 files and provides tools to convert from NumPy. The .h5 file should contain a dataset named "data" with a 3D array: one scan axis and two detector axes.

PyPty also accepts 4D Nion-style NumPy arrays (with accompanying JSON metadata).

Output Format

By default, PyPty saves all output as .npy files inside an output_folder. The folder structure may look like this:

output_folder
├── cg.npy                              **overwritable checkpoint for scan grid**
├── cp.npy                              **overwritable checkpoint for probe**
├── co.npy                              **overwritable checkpoint for object**
├── checkpoint_obj_epoch_N.npy          **checkpoint for object at epoch N**
├── checkpoint_probe_epoch_N.npy        **checkpoint for probe at epoch N**
├── checkpoint_positions_epoch_N.npy    **checkpoint for scan grid at epoch N**
├── params.pkl                          **parameter file of your reconstruction**
├── loss.csv                            **.csv log-file**
├── tcbf                                **folder  with tcBF results**
│   ├── tcbf_image_upsampling_5.npy     **upsampled tcBF image_**
│   ├── tcbf_image_N.png                **intermediate tcBF image at iteration N in .png format**
│   ├── estimated_shifts_N.npy          **Fitted shifts at iteration N in .npy format**
│   ├── aberrations_N.npy               **Fitted aberrations (in Angstrom) at iteration N in .npy format**
│   ├── PL_angle_deg.npy                **array constaining fitted rotation angles at all iterations in .npy format**
│   ├── aberrations_A.npy               **2d array constaining fitted aberrations at all iterations in .npy format**
└── dpc                                 **folder  with DPC results**
│   ├── idpc.npy                        **fft-based dpc phase**
│   ├── iterative_dpc.npy               **DPC phase (iterative reconstruction)**
└── wdd                                 **folder  with WDD results**
    ├── object.npy                      **complex object (WDD ptychography)**

You can also convert an output folder into single Nexus .nxs file via pypty.utils.convert_to_nxs() function.

Examples

Example workflows are available in the examples folder on GitHub.

For a quick start, check out the following:

Relevant Literature

If you have any questions after reading this guide, the following papers, books and links might explain the working principle of the code:

Multi-slice formalism and the NN-style approach

1) Earl J. Kirkland. Advanced Computing in Electron Microscopy

2) W. Van den Broek and C. Koch. General framework for quantitative three-dimensional reconstruction from arbitrary detection geometries in TEM

3) W. Van den Broek and C. Koch. Method for Retrieval of the Three-Dimensional Object Potential by Inversion of Dynamical Electron Scattering

Error metrics:

LSQ:

4) M. Schloz et al. Overcoming information reduced data and experimentally uncertain parameters in ptychography with regularized optimization

5) M. Du et al. Adorym: a multi-platform generic X-ray image reconstruction framework based on automatic differentiation

Maximum Likelihood (ML):

6) P. Thibault and M. Guizar-Sicairos. Maximum-likelihood refinement for coherent diffractive imaging

Compressed LSQ:

7) A. Gladyshev et al. Lossy Compression of Electron Diffraction Patterns for Ptychography via Change of Basis

lsq_sqrt and lsq_sqrt2:

8) P. Godard et al. (2012). Noise models for low counting rate coherent diffraction imaging

Mixed state formalism:

9) P Thibault & A.Menzel Reconstructing state mixtures from diffraction measurements— Flux-preserving formalism (for near-field imaging)

Near-field imaging

10) C. Koch A flux-preserving non-linear inline holography reconstruction algorithm for partially coherent electrons

Tilted propagator:

11) Earl J. Kirkland. Advanced Computing in Electron Microscopy

12) H. She, J. Cui and R. Yu. Deep sub-angstrom resolution imaging by electron ptychography with misorientation correction

Regularization constaints:

13) M. Schloz et al. Overcoming information reduced data and experimentally uncertain parameters in ptychography with regularized optimization

14) A. Gladyshev et al. Lossy Compression of Electron Diffraction Patterns for Ptychography via Change of Basis

Linesearch

15) L. Armijo (1966). Minimization of functions having Lipschitz continuous first partial derivatives 16) P. Wolfe (1969). Convergence Conditions for Ascent Methods

BFGS algotithm

17) C. G. Broyden (1970). The convergence of a class of double-rank minimization algorithms

18) R. Fletcher (1970). A New Approach to Variable Metric Algorithms

19) D. Goldfarb (1970). A Family of Variable Metric Updates Derived by Variational Means

20) D. F. Shanno (1970). Conditioning of quasi-Newton methods for function minimization

Complex derivatives

21) W. Wirtinger (1927). Zur formalen theorie der funktionen von mehr komplexen veränderlichen.

pypty.direct - PyPty (python + ptychography)

pypty.direct

wdd

Perform Wigner Distribution Deconvolution (WDD).

This function applies Wigner Distribution Deconvolution to the provided data, allowing for enhanced reconstruction of complex objects and probes. It handles both GPU (via CuPy) and CPU (via NumPy) computations based on the availability of CuPy. The pypty_params dictionary must be prepared via the initialize module.

PARAMETER DESCRIPTION
pypty_params

Dictionary containing calibrated parameters, including paths and settings for data processing.

TYPE: dict

eps_wiener

Epsilon parameter for the Wiener filter. Default is 1e-3.

TYPE: float DEFAULT: 0.001

thresh

If provided, eps_wiener is ignored. Denominator values below this threshold are set to 1, and the corresponding numerator values are set to 0.

TYPE: float DEFAULT: None

save

Whether to save output files (False by default). Ignored if save_preprocessing_files is specified in pypty_params.

TYPE: bool DEFAULT: 0

RETURNS DESCRIPTION
deconvolved_object

2D deconvolved complex object.

TYPE: ndarray

Notes

Make sure pypty_params includes all necessary paths and data arrays prior to calling this function.

pypty.dpc - PyPty (python + ptychography)

pypty.dpc

get_curl

Compute the standard deviation of the curl of a rotated DPC vector field. This is the objective function for minimization. This particular function was copied from a DPC plugin written by Jordan Hachtel.

PARAMETER DESCRIPTION
angle

Rotation angle in radians.

TYPE: float

dpcx

X-component of the DPC signal.

TYPE: ndarray

dpcy

Y-component of the DPC signal.

TYPE: ndarray

RETURNS DESCRIPTION
float

Standard deviation of the curl after rotation.

get_curl_derivative

Compute the derivative of the curl-based objective function with respect to rotation angle.

PARAMETER DESCRIPTION
angle

Rotation angle in radians.

TYPE: float

dpcx

X-component of the DPC signal.

TYPE: ndarray

dpcy

Y-component of the DPC signal.

TYPE: ndarray

RETURNS DESCRIPTION
float

Derivative of the curl-based objective function.

GetPLRotation

Estimate rotation angle that minimizes the curl of the DPC signal.

PARAMETER DESCRIPTION
dpcx

X-component of the DPC signal (2D array).

TYPE: ndarray

dpcy

Y-component of the DPC signal (2D array).

TYPE: ndarray

RETURNS DESCRIPTION
float

Optimal rotation angle in radians.

fft_based_dpc

FFT-based DPC phase reconstruction. If you setted up the pypty_params properly, you would only need to specify the hpass and lpass values, both are non-negative floats.

PARAMETER DESCRIPTION
pypty_params

PyPty parameter dictionary with dataset and calibration settings.

TYPE: dict

hpass

High-pass filtering coefficient (default is 0).

TYPE: float DEFAULT: 0

lpass

Low-pass filtering coefficient (default is 0).

TYPE: float DEFAULT: 0

save

Whether to save the reconstructed phase (default is False).

TYPE: bool DEFAULT: False

comx

Precomputed center-of-mass x-component.

TYPE: ndarray or None DEFAULT: None

comy

Precomputed center-of-mass y-component.

TYPE: ndarray or None DEFAULT: None

plot

If True, display the phase reconstruction.

TYPE: bool DEFAULT: False

RETURNS DESCRIPTION
pot

Reconstructed 2D phase image.

TYPE: ndarray

pypty_params

Updated parameter dictionary with computed COM and rotation angle.

TYPE: dict

iterative_dpc

Iterative DPC phase reconstruction. If you setted up the pypty_params properly, you would only need to specify the hpass and lpass values, both are non-negative floats.

PARAMETER DESCRIPTION
pypty_params

PyPty parameter dictionary.

TYPE: dict

num_iterations

Number of gradient descent iterations (default is 100).

TYPE: int DEFAULT: 100

beta

Step reduction factor for backtracking (default is 0.5).

TYPE: float DEFAULT: 0.5

hpass

High-pass filtering coefficient (default is 0).

TYPE: float DEFAULT: 0

lpass

Low-pass filtering coefficient (default is 0).

TYPE: float DEFAULT: 0

step_size

Initial gradient descent step size (default is 0.1).

TYPE: float DEFAULT: 0.1

COMx

X-component of COM map.

TYPE: ndarray or None DEFAULT: None

COMy

Y-component of COM map.

TYPE: ndarray or None DEFAULT: None

px_size

Scan step size in Ångströms.

TYPE: float or None DEFAULT: None

print_flag

Whether to print progress information (default is False).

TYPE: bool DEFAULT: False

save

Whether to save the result to disk (default is False).

TYPE: bool DEFAULT: False

select

Optional binary mask to constrain reconstruction.

TYPE: ndarray or None DEFAULT: None

plot

If True, plot the reconstruction result.

TYPE: bool DEFAULT: True

use_backtracking

Whether to use backtracking line search (default is True).

TYPE: bool DEFAULT: True

pad_width

Padding width to suppress FFT boundary artifacts (default is 5).

TYPE: int DEFAULT: 5

RETURNS DESCRIPTION
padded_phase

Reconstructed 2D phase image.

TYPE: ndarray

iterative_poisson_solver

Iterative solver for Poisson equation given a Laplacian map.

PARAMETER DESCRIPTION
laplace

Input 2D array representing the Laplacian of the desired phase.

TYPE: ndarray

num_iterations

Number of iterations (default is 100).

TYPE: int DEFAULT: 100

beta

Step size reduction factor (default is 0.5).

TYPE: float DEFAULT: 0.5

hpass

High-pass filtering parameter (default is 0).

TYPE: float DEFAULT: 0

lpass

Low-pass filtering parameter (default is 0).

TYPE: float DEFAULT: 0

select

Optional binary mask to restrict updates.

TYPE: ndarray or None DEFAULT: None

px_size

Pixel size in Ångströms (default is 1).

TYPE: float DEFAULT: 1

print_flag

If True, print convergence status (default is False).

TYPE: bool DEFAULT: False

step_size

Initial gradient descent step size (default is 0.1).

TYPE: float DEFAULT: 0.1

use_backtracking

Whether to use backtracking line search (default is True).

TYPE: bool DEFAULT: True

pad_width

Number of pixels to pad around the solution (default is 1).

TYPE: int DEFAULT: 1

xp

Backend array library (NumPy or CuPy, default is NumPy).

TYPE: module DEFAULT: numpy

RETURNS DESCRIPTION
ndarray

Reconstructed 2D phase from the input Laplacian.

pypty.fft - PyPty (python + ptychography)

pypty.fft

fftfreq

Wrapper for fftfreq function.

PARAMETER DESCRIPTION
length

Length of the output array.

TYPE: int

sampling

Sample spacing (default is 1).

TYPE: float DEFAULT: 1

RETURNS DESCRIPTION
ndarray

Discrete Fourier Transform sample frequencies.

ifftfreq

Wrapper for ifftfreq function.

PARAMETER DESCRIPTION
length

Length of the output array.

TYPE: int

sampling

Sample spacing (default is 1).

TYPE: float DEFAULT: 1

RETURNS DESCRIPTION
ndarray

Discrete inverse Fourier Transform sample frequencies.

fftshift

Wrapper for fftshift function.

PARAMETER DESCRIPTION
array

Input array to be shifted.

TYPE: ndarray

RETURNS DESCRIPTION
ndarray

Shifted array.

ifftshift

Wrapper for ifftshift function.

PARAMETER DESCRIPTION
array

Input array to be inverse shifted.

TYPE: ndarray

RETURNS DESCRIPTION
ndarray

Inverse shifted array.

shift_fft2

Wrapper for xp.fft.fftshift(xp.fft.fft2(...)) functions.

PARAMETER DESCRIPTION
arr

Input array to be transformed.

TYPE: ndarray

axes

Axes over which to compute the FFT (default is (0, 1)).

TYPE: tuple of int DEFAULT: (0, 1)

overwrite_x

If True, allow overwriting the input array (default is False).

TYPE: bool DEFAULT: False

RETURNS DESCRIPTION
ndarray

2D Fourier Transform of the input array, shifted.

fft2

Wrapper for fft2 function.

PARAMETER DESCRIPTION
arr

Input array to be transformed.

TYPE: ndarray

axes

Axes over which to compute the FFT (default is (0, 1)).

TYPE: tuple of int DEFAULT: (0, 1)

overwrite_x

If True, allow overwriting the input array (default is False).

TYPE: bool DEFAULT: False

RETURNS DESCRIPTION
ndarray

2D Fourier Transform of the input array.

ifft2

Wrapper for ifft2 function.

PARAMETER DESCRIPTION
arr

Input array to be transformed.

TYPE: ndarray

axes

Axes over which to compute the inverse FFT (default is (0, 1)).

TYPE: tuple of int DEFAULT: (0, 1)

overwrite_x

If True, allow overwriting the input array (default is False).

TYPE: bool DEFAULT: False

RETURNS DESCRIPTION
ndarray

2D inverse Fourier Transform of the input array.

ifft2_ishift

Wrapper for xp.fft.ifft2(xp.fft.ifftshift(...)) function.

PARAMETER DESCRIPTION
arr

Input array to be transformed.

TYPE: ndarray

axes

Axes over which to compute the inverse FFT (default is (0, 1)).

TYPE: tuple of int DEFAULT: (0, 1)

overwrite_x

If True, allow overwriting the input array (default is False).

TYPE: bool DEFAULT: False

RETURNS DESCRIPTION
ndarray

2D inverse Fourier Transform of the input array, after shifting.

shift_fftn

Wrapper for xp.fft.fftshift(xp.fft.fftn(...)) function.

PARAMETER DESCRIPTION
arr

Input array to be transformed.

TYPE: ndarray

axes

Axes over which to compute the FFT (default is (0, 1, 2)).

TYPE: tuple of int DEFAULT: (0, 1, 2)

RETURNS DESCRIPTION
ndarray

N-dimensional Fourier Transform of the input array, shifted.

ifftn_ishift

Wrapper for xp.fft.ifftn(xp.fft.ifftshift(...)) function.

PARAMETER DESCRIPTION
arr

Input array to be transformed.

TYPE: ndarray

axes

Axes over which to compute the inverse FFT (default is (0, 1, 2)).

TYPE: tuple of int DEFAULT: (0, 1, 2)

RETURNS DESCRIPTION
ndarray

N-dimensional inverse Fourier Transform of the input array, after shifting.

ifftn

Wrapper for ifftn function.

PARAMETER DESCRIPTION
arr

Input array to be transformed.

TYPE: ndarray

axes

Axes over which to compute the inverse FFT (default is (0, 1, 2)).

TYPE: tuple of int DEFAULT: (0, 1, 2)

RETURNS DESCRIPTION
ndarray

N-dimensional inverse Fourier Transform of the input array.

fftn

Wrapper for fftn function.

PARAMETER DESCRIPTION
arr

Input array to be transformed.

TYPE: ndarray

axes

Axes over which to compute the FFT (default is (0, 1, 2)).

TYPE: tuple of int DEFAULT: (0, 1, 2)

RETURNS DESCRIPTION
ndarray

N-dimensional Fourier Transform of the input array.

pypty.initialize - PyPty (python + ptychography)

pypty.initialize

create_pypty_data

Create a PyPty-style .h5 dataset from 4D-STEM data.

PARAMETER DESCRIPTION
data

Path to .h5 or .npy data file or a 4D numpy array [scan_y, scan_x, ky, kx].

TYPE: str or ndarray

path_output

Output file path for the PyPty .h5 dataset.

TYPE: str

swap_axes

Swap the last two axes (kx, ky). Default is False.

TYPE: bool DEFAULT: False

flip_ky

Flip the data along specific axes. Default is False.

TYPE: bool DEFAULT: False

flip_kx

Flip the data along specific axes. Default is False.

TYPE: bool DEFAULT: False

flip_y

Flip the data along specific axes. Default is False.

TYPE: bool DEFAULT: False

flip_x

Flip the data along specific axes. Default is False.

TYPE: bool DEFAULT: False

comcalc_len

Number of patterns to use to estimate center-of-mass. Default is 1000.

TYPE: int DEFAULT: 1000

comx

Predefined center-of-mass. If None, it will be computed.

TYPE: int or None DEFAULT: None

comy

Predefined center-of-mass. If None, it will be computed.

TYPE: int or None DEFAULT: None

bin

Spatial binning factor on the diffraction patterns. Default is 1.

TYPE: int DEFAULT: 1

crop_left

Crop edges of patterns. Defaults are None.

TYPE: int or None DEFAULT: None

crop_right

Crop edges of patterns. Defaults are None.

TYPE: int or None DEFAULT: None

crop_top

Crop edges of patterns. Defaults are None.

TYPE: int or None DEFAULT: None

crop_bottom

Crop edges of patterns. Defaults are None.

TYPE: int or None DEFAULT: None

normalize

Normalize pattern sums to 1. Default is False.

TYPE: bool DEFAULT: False

cutoff_ratio

Mask out pixels farther than cutoff_ratio × max_radius. Default is None.

TYPE: float or None DEFAULT: None

pad_k

Padding to apply to diffraction patterns. Default is 0.

TYPE: int DEFAULT: 0

data_dtype

Output data type. Default is np.float32.

TYPE: dtype DEFAULT: float32

rescale

Scale factor for intensity. Default is 1.

TYPE: float DEFAULT: 1

exist_ok

If True, skip writing if file exists. Default is True.

TYPE: bool DEFAULT: True

RETURNS DESCRIPTION
None
Notes

Saves a .h5 file containing processed 4D-STEM data with standardized formatting for PyPty.

append_exp_params

Attach experimental parameters to a PyPty preset dictionary and callibrate an extisting PyPty preset to new data.

PARAMETER DESCRIPTION
experimental_params

Dictionary containing experimental metadata and setup for PyPty reconstruction.

TYPE: dict

pypty_params

Existing PyPty preset to update, a filepath to a preset, or None to create a new one.

TYPE: dict or str or None DEFAULT: None

RETURNS DESCRIPTION
dict

Updated PyPty parameter dictionary.
Notes

experimental_params should contain following entries:

data_path - path to a PyPty-style 3d .h5 file [N_measurements, ky,kx] or .npy Nion-style 4d-stem dataset (or 3d .npy dataset)

masks - 3d numpy array or None. if data is compressed provide the virtual detectors (masks) shape should be [N_masks,ky,kx]

output_folder - path to an outputfolder where the results will be stored

path_json - path to a nion-style json file with metadata (optional)

acc_voltage - float, accelerating voltage in kV

One or multiple of the following callibrations:
    rez_pixel_size_A - reciprocal pixel size in Å^-1
    rez_pixel_size_mrad - reciprocal pixel size in mrad
    conv_semiangle_mrad - beam convergence semi-angle in mrad
    aperture - (optional)- binary 2D mask
    bright_threshold - threshold to estimate an aperture, everything above threshold times maximum value in a pacbed will be concidered as bright field disk.

data_pad - int, reciprocal space padding. If None (default), pading is 1/4 of the total width of a diffraction pattern
upsample_pattern - int, default 1 (no upsampling)

aberrations - list or 1d numpy array containing beam aberrations (in Å). Aberrations are stored in Krivanek notation, e.g. C10, C12a, C12b, C21a, C21b, C23a, C23b, C30 etc

defocus - float, default 0. Extra probe defocus besides the one contained in aberrations.

scan_size - tuple of two ints, number of scan points along slow (y) and fast (x) axes. Optional. If no scan step or position grid is provided, it will be used to get the scan step

scan_step_A - float, scan step (STEM pixel size) in Å.

fov_nm - float, FOV along the fast axis in nm.

special_postions_A - 2d numpy array, default None. If you acquiered a data on a special non-rectangular grid, please specify the positions in Å via this array for all measurements in a following form: [y_0,x_0],[y_1,x_1],....[y_n,x_n]]

transform_axis_matrix- 2x2 matrix for postions transformation

PLRotation_deg - float, rotation angle between scan and detector axes. Default None. If None, a DPC measurement will be exectuted to get this angle. !!!!!!! Note that negative PLRotation_deg values rotate scan counter clockwise and diffraction space clockwise !!!!!!!!!!!

flip_ky - boolean Flag. Default is False. If no PyPty-style h5 data was created, this flag will flip the y-axis of diffraction patterns.

total_thickness - total thickness of a sample in Å. Has no effect if num_slices is 1 and propagation method (pypty_params entry) is multislice

num_slices - integer, number of slices, default is 1.

plot - boolean Flag, default is True

print_flag - integer. Default is 1. If 0 nothing will be printed. 1 prints only thelatest state of the computation, 2 prints every state as a separate line. 3 prints the linesearch progress in iterative optimization. 4 prints everything that 3 does and if constraints are applied, it prints how they contribute so that a user can configure the weights properly.

save_preprocessing_files - Boolean Flag. Default is True.

get_offset

Compute pixel offsets between scan grid and reconstruction grid. In PyPty framework, scan grid is usually rotated to compensate the misalignment between scan- and detector- axes. Also, a reconstruction grid is larger than the scanned FOV, this is done to accomodate the extent of the probe.

PARAMETER DESCRIPTION
x_range

Scan dimensions.

TYPE: int

y_range

Scan dimensions.

TYPE: int

scan_step_A

STEM scan step size in Å.

TYPE: float

detector_pixel_size_rezA

Reciprocal space pixel size in Å⁻¹.

TYPE: float

patternshape

Shape of diffraction patterns.

TYPE: tuple

rot_angle_deg

Rotation between scan and detector axes (degrees).

TYPE: float DEFAULT: 0

RETURNS DESCRIPTION
offy, offx : float

Offset values (in reconstruction pixels).

get_positions_pixel_size

Generate scan positions in reconstruction pixel units.

PARAMETER DESCRIPTION
x_range

Scan grid size.

TYPE: int

y_range

Scan grid size.

TYPE: int

scan_step_A

STEM scan step size (Å).

TYPE: float

detector_pixel_size_rezA

Pixel size in reciprocal space (Å⁻¹).

TYPE: float

patternshape

Shape of the diffraction pattern.

TYPE: tuple

rot_angle_deg

Scan-detector rotation angle in degrees. Default is 0.

TYPE: float DEFAULT: 0

flip_x

Flip scan axes. Default is False.

TYPE: bool DEFAULT: False

flip_y

Flip scan axes. Default is False.

TYPE: bool DEFAULT: False

print_flag

Print pixel size. Default is False.

TYPE: bool DEFAULT: False

transform_axis_matrix

Optional 2x2 matrix to apply to positions.

TYPE: array_like DEFAULT: eye(2)

RETURNS DESCRIPTION
positions

Scan positions in reconstruction pixels.

TYPE: ndarray

pixel_size

Size of one reconstruction pixel in Å.

TYPE: float

get_grid_for_upsampled_image

Map coordinates of an upsampled image onto the reconstruction grid.

This function calculates where pixel of an arbitary image (e.g. upsampled tcBF image) will land on a grid corresponding to a ptychographic reconstruction.

PARAMETER DESCRIPTION
pypty_params

Dictionary of PyPty reconstruction parameters.

TYPE: dict

image

2D image (e.g., upsampled tcBF) to map.

TYPE: ndarray

image_pixel_size

Pixel size of the image in Å.

TYPE: float

left_zero_of_scan_grid

Pixel offset on left side of image relative to scan grid. Default is 0.

TYPE: int DEFAULT: 0

top_zero_of_scan_grid

Pixel offset on top side of image relative to scan grid. Default is 0.

TYPE: int DEFAULT: 0

RETURNS DESCRIPTION
sc

Array of pixel coordinates [[y, x], ...] in reconstruction grid units.

TYPE: ndarray

get_ptycho_obj_from_scan

Construct an initial object guess using interpolated phase and amplitude maps. You can use output of dpc, wdd of tcBF reconstructions to generate it.

PARAMETER DESCRIPTION
params

PyPty parameter dictionary.

TYPE: dict

num_slices

Number of slices or "auto" to estimate from max phase shift.

TYPE: int or str DEFAULT: None

array_phase

2D phase map to interpolate.

TYPE: ndarray DEFAULT: None

array_abs

2D amplitude map to interpolate.

TYPE: ndarray DEFAULT: None

scale_phase

Scale factor for phase.

TYPE: float DEFAULT: 1

scale_abs

Scale factor for amplitude.

TYPE: float DEFAULT: 1

scan_array_A

Spatial reference grid for the input maps (in Å).

TYPE: ndarray or None DEFAULT: None

fill_value_type

Padding strategy outside scanned region: None, "edge", or "median".

TYPE: str or None DEFAULT: None

RETURNS DESCRIPTION
dict

Updated PyPty parameter dictionary with object guess.

create_aberrations_chunks

Create chunks, i.e. multiple subscans with independent beam aberrations. Usefull for large fields of view where the beam is varyying. If applied, the iterative reconstruction will have the same beam in each subscan, but apply a different CTF in each of these regions.

PARAMETER DESCRIPTION
pypty_params

PyPty parameter dictionary.

TYPE: dict

chop_size

Size of each subscan region (in scan points).

TYPE: int

n_abs

Number of aberration coefficients per region.

TYPE: int

RETURNS DESCRIPTION
dict

Updated parameter dictionary with aberration array and marker.

create_probe_marker_chunks

Creates chunks, i.e. multiple subscans with independent beam aberrations. Usefull for large fields of view where the beam is varyying. If applied, the iterative reconstruction will have the a differenet beam in each of these subscans.

PARAMETER DESCRIPTION
pypty_params

PyPty parameter dictionary.

TYPE: dict

chop_size

Size of each subscan region (in scan points).

TYPE: int

RETURNS DESCRIPTION
dict

Updated dictionary with probe marker.

create_sub_sequence

Define a measurement subsequence for local reconstructions.

PARAMETER DESCRIPTION
pypty_params

PyPty parameter dictionary.

TYPE: dict

left

Leftmost scan coordinate.

TYPE: int

top

Top scan coordinate.

TYPE: int

width

Width of subregion (in scan points).

TYPE: int

height

Height of subregion (in scan points).

TYPE: int

sub

Sampling factor (take every Nth point).

TYPE: int

RETURNS DESCRIPTION
dict

Updated parameter dictionary with sequence key.

create_sequence_from_points

Create scan subsequence around specified feature points.

PARAMETER DESCRIPTION
pypty_params

PyPty parameter dictionary.

TYPE: dict

yf

Y-coordinates of feature points (in scan points).

TYPE: list of int

xf

X-coordinates of feature points.

TYPE: list of int

width_roi

Width of the reconstruction window around each point.

TYPE: int DEFAULT: 20

RETURNS DESCRIPTION
list

List of scan indices to reconstruct.

rotate_scan_grid

Apply a rigid rotation to the scan grid.

PARAMETER DESCRIPTION
pypty_params

PyPty parameter dictionary.

TYPE: dict

angle_deg

Rotation angle in degrees.

TYPE: float

RETURNS DESCRIPTION
dict

Updated dictionary with rotated positions and angle.

conjugate_beam

Apply beam conjugation (flip defocus and aberrations).

PARAMETER DESCRIPTION
pypty_params

PyPty parameter dictionary.

TYPE: dict

RETURNS DESCRIPTION
dict

Updated dictionary with conjugated probe and CTF.

get_focussed_probe_from_vacscan

Reconstruct a focused probe from a vacuum PACBED pattern.

PARAMETER DESCRIPTION
pypty_params

PyPty parameter dictionary.

TYPE: dict

mean_pattern

Measured PACBED from vacuum.

TYPE: ndarray

RETURNS DESCRIPTION
dict

Updated dictionary with a probe estimate.

append_aperture_to_params

Append a measured aperture to the reconstruction parameters.

PARAMETER DESCRIPTION
pypty_params

PyPty parameter dictionary.

TYPE: dict

mean_pattern

Aperture image to be rescaled and added.

TYPE: ndarray

RETURNS DESCRIPTION
dict

Updated dictionary with aperture.

tiltbeamtodata

Align the probe momentum to the center of the measured PACBED pattern.

PARAMETER DESCRIPTION
pypty_params

PyPty parameter dictionary.

TYPE: dict

align_type

Type of alignment ("com" or "cross_corr").

TYPE: str DEFAULT: 'com'

RETURNS DESCRIPTION
dict

Updated dictionary with shifted probe.

get_approx_beam_tilt

Estimate scan-position-dependent beam tilt from PACBED.

PARAMETER DESCRIPTION
pypty_params

PyPty parameter dictionary.

TYPE: dict

power

Degree of polynomial fitting.

TYPE: int or str DEFAULT: 3

make_binary

If True or float > 0, binarize patterns.

TYPE: bool or float DEFAULT: False

percentile_filter_value

Value for optional percentile filtering.

TYPE: float or None DEFAULT: None

percentile_filter_size

Filter size if filtering is enabled.

TYPE: int DEFAULT: 10

RETURNS DESCRIPTION
dict

Updated dictionary with estimated tilts.

pypty.iterative - PyPty (python + ptychography)

pypty.iterative

run

Launch iterative reconstuction.

PARAMETER DESCRIPTION
pypty_params

Dictionary containing calibrated parameters, including paths and settings for data processing.

TYPE: dict

Notes

pypty_params dictionary can be constructed from a predefined preset and a given dataset via append_exp_params() function. Full list of expected entries can be found in the documentation,

bfgs_update

This is one of the core functions of PyPty. It performs updates of all active reconstruction parameters (object, probe, positions, tilts, etc.) via l-BFGS algorithm.

PARAMETER DESCRIPTION
Params

Way to many to describe right now

TYPE: list

RETURNS DESCRIPTION
total_loss

Total loss value.

TYPE: float

this_sse

Sum of squared errors.

TYPE: float

constraint_contributions

List of reg. constraint values for this epoch

TYPE: list

actual_step

Linesearch step that was found during this iteration

TYPE: float

count

Number of linesearch iterations (calls of loss_and_direction) that was required during this epoch

TYPE: int

d_value

Value of the direction derivative at this epoch

TYPE: float

new_d_value

Value of the direction derivative at the newly estimated point

TYPE: float

warnings

Warnings during this epoch

TYPE: string

reset_bfgs_history

Reset a global variable history_bfgs that contains information about previous steps.

pypty.multislice_core - PyPty (python + ptychography)

pypty.multislice_core

multislice

Simulate multislice wave propagation using a classic split-step integrator (2nd order precision with respect to slice thickness if beam is optimized).

PARAMETER DESCRIPTION
full_probe

Probe wavefunction with shape [N_batch, y,x, modes]

TYPE: ndarray

this_obj_chopped

Object slices with shape [N_batch, y,x, z, modes].

TYPE: ndarray

num_slices

Number of object slices.

TYPE: int

n_obj_modes

Number of object modes.

TYPE: int

n_probe_modes

Number of probe modes.

TYPE: int

this_distances

Slice thicknesses.

TYPE: ndarray

this_wavelength

Electron wavelength.

TYPE: float

q2

Spatial frequency grids.

TYPE: ndarray

qx

Spatial frequency grids.

TYPE: ndarray

qy

Spatial frequency grids.

TYPE: ndarray

exclude_mask

Mask to exclude undesired frequencies.

TYPE: ndarray

is_single_dist

If True, use the same distance for all slices.

TYPE: bool

this_tan_x

Beam tilts with shape N_batch

TYPE: ndarray

this_tan_y

Beam tilts with shape N_batch

TYPE: ndarray

damping_cutoff_multislice

Damping frequency cutoff.

TYPE: float

smooth_rolloff

Rolloff rate for the damping filter.

TYPE: float

master_propagator_phase_space

Full propagator in Fourier space (optional).

TYPE: ndarray or None

half_master_propagator_phase_space

Half-step propagator (optional).

TYPE: ndarray or None

mask_clean

Clean propagation mask.

TYPE: ndarray

waves_multislice

This array contains interediate exit-waves

TYPE: ndarray

wave

This array contains final exit-wave

TYPE: ndarray

default_float

Numerical types.

TYPE: dtype

default_complex

Numerical types.

TYPE: dtype

RETURNS DESCRIPTION
waves_multislice

Multislice stack of propagated waves.

TYPE: ndarray

wave

Final exit wave.

TYPE: ndarray

multislice_grads

Compute gradients for classic multislice propagation model (object, probe, and tilts).

PARAMETER DESCRIPTION
dLoss_dP_out

Gradient of the loss with respect to the final propagated wave.

TYPE: ndarray

waves_multislice

Intermediate wave stack from the forward multislice pass.

TYPE: ndarray

this_obj_chopped

4D sliced object [batch, y, x, z, modes].

TYPE: ndarray

object_grad

Gradient accumulator for object slices.

TYPE: ndarray

tilts_grad

Accumulator for tilt gradients.

TYPE: ndarray

is_single_dist

If True, slice distances are constant.

TYPE: bool

this_distances

Per-slice thicknesses.

TYPE: ndarray

exclude_mask

Frequency mask for FFT operations.

TYPE: ndarray

this_wavelength

Probe wavelength (Å).

TYPE: float

q2

Spatial frequency grids.

TYPE: ndarray

qx

Spatial frequency grids.

TYPE: ndarray

qy

Spatial frequency grids.

TYPE: ndarray

this_tan_x

Beam tilt values per batch.

TYPE: float

this_tan_y

Beam tilt values per batch.

TYPE: float

num_slices

Number of slices.

TYPE: int

n_obj_modes

Number of object modes.

TYPE: int

tiltind

Index in tilt update array.

TYPE: int

master_propagator_phase_space

Full Fourier propagation kernel.

TYPE: ndarray

this_step_tilts

Whether tilt gradient is updated.

TYPE: int

damping_cutoff_multislice

Damping cutoff for high-frequency noise.

TYPE: float

smooth_rolloff

Width of damping transition.

TYPE: float

tilt_mode

Mode selector for tilt optimization.

TYPE: int

compute_batch

Current batch size.

TYPE: int

mask_clean

FFT domain mask.

TYPE: ndarray

this_step_probe

Whether to compute probe gradient.

TYPE: int

this_step_obj

Whether to compute object gradient.

TYPE: int

this_step_pos_correction

(Unused) Flag for positional corrections.

TYPE: int

masked_pixels_y

Indices for applying gradients to global object.

TYPE: ndarray

masked_pixels_x

Indices for applying gradients to global object.

TYPE: ndarray

default_float

Floating-point type.

TYPE: dtype

default_complex

Complex type.

TYPE: dtype

helper_flag_4

If True, return probe gradient; else return None.

TYPE: bool

RETURNS DESCRIPTION
object_grad

Gradient for object slices.

TYPE: ndarray

interm_probe_grad

Gradient for input probe (if helper_flag_4 is True).

TYPE: ndarray or None

tilts_grad

Updated tilt gradient.

TYPE: ndarray

better_multislice

Simulate multislice wave propagation using an additive split-step method (5th order precision with respect to slice thickness).

PARAMETER DESCRIPTION
full_probe

Probe wavefunction with shape [N_batch, y,x, modes]

TYPE: ndarray

this_obj_chopped

Object slices with shape [N_batch, y,x, z, modes].

TYPE: ndarray

num_slices

Number of object slices.

TYPE: int

n_obj_modes

Number of object modes.

TYPE: int

n_probe_modes

Number of probe modes.

TYPE: int

this_distances

Slice thicknesses.

TYPE: ndarray

this_wavelength

Electron wavelength.

TYPE: float

q2

Spatial frequency grids.

TYPE: ndarray

qx

Spatial frequency grids.

TYPE: ndarray

qy

Spatial frequency grids.

TYPE: ndarray

exclude_mask

Mask to exclude undesired frequencies.

TYPE: ndarray

is_single_dist

If True, use the same distance for all slices.

TYPE: bool

this_tan_x

Beam tilts with shape N_batch

TYPE: ndarray

this_tan_y

Beam tilts with shape N_batch

TYPE: ndarray

damping_cutoff_multislice

Damping frequency cutoff.

TYPE: float

smooth_rolloff

Rolloff rate for the damping filter.

TYPE: float

master_propagator_phase_space

Full propagator in Fourier space (optional).

TYPE: ndarray or None

half_master_propagator_phase_space

Half-step propagator (optional).

TYPE: ndarray or None

mask_clean

Clean propagation mask.

TYPE: ndarray

waves_multislice

This array contains interediate exit-waves

TYPE: ndarray

wave

This array contains final exit-wave

TYPE: ndarray

default_float

Numerical types.

TYPE: dtype

default_complex

Numerical types.

TYPE: dtype

RETURNS DESCRIPTION
waves_multislice

Multislice stack of propagated waves.

TYPE: ndarray

wave

Final exit wave.

TYPE: ndarray

better_multislice_grads

Compute gradients of object, probe, and tilts for the "better_multislice" wave propagation model.

PARAMETER DESCRIPTION
dLoss_dP_out

Gradient of the loss with respect to the final exit wave.

TYPE: ndarray

waves_multislice

Stack of intermediate wavefields saved during the forward pass.

TYPE: ndarray

this_obj_chopped

The sliced object with shape [batch, y, x, z, modes].

TYPE: ndarray

object_grad

Gradient accumulator for the object slices.

TYPE: ndarray

tilts_grad

Gradient accumulator for the tilts.

TYPE: ndarray

is_single_dist

Whether all slices have the same thickness.

TYPE: bool

this_distances

Thickness per slice.

TYPE: ndarray

exclude_mask

Frequency mask used in propagation.

TYPE: ndarray

this_wavelength

Wavelength of the probe in Ångströms.

TYPE: float

q2

Spatial frequency grids.

TYPE: ndarray

qx

Spatial frequency grids.

TYPE: ndarray

qy

Spatial frequency grids.

TYPE: ndarray

this_tan_x

Beam tilt values per batch.

TYPE: float

this_tan_y

Beam tilt values per batch.

TYPE: float

num_slices

Number of slices in the object.

TYPE: int

n_probe_modes

Number of probe modes.

TYPE: int

n_obj_modes

Number of object modes.

TYPE: int

tiltind

Index for updating tilts_grad.

TYPE: int

this_step_tilts

Whether to update tilts (0 = off).

TYPE: int

master_propagator_phase_space

Full propagator for the current slice.

TYPE: ndarray

half_master_propagator_phase_space

Half-step propagator.

TYPE: ndarray

damping_cutoff_multislice

Cutoff for high frequencies in damping.

TYPE: float

smooth_rolloff

Smoothing width for damping filter.

TYPE: float

tilt_mode

Specifies which tilts to optimize.

TYPE: int

compute_batch

Number of scan positions processed in batch.

TYPE: int

mask_clean

FFT mask used to remove unstable frequencies.

TYPE: ndarray

masked_pixels_y

Indices to scatter object gradients into global coordinates.

TYPE: ndarray

masked_pixels_x

Indices to scatter object gradients into global coordinates.

TYPE: ndarray

default_float

Floating point precision.

TYPE: dtype

default_complex

Complex precision.

TYPE: dtype

RETURNS DESCRIPTION
object_grad

Updated gradient of the object slices.

TYPE: ndarray

interm_probe_grad

Gradient of the probe (summed over object modes).

TYPE: ndarray

tilts_grad

Updated tilt gradients.

TYPE: ndarray

yoshida_multislice

Simulate multislice wave propagation using an yoshida integrator (5th order precision with respect to slice thickness).

PARAMETER DESCRIPTION
full_probe

Probe wavefunction with shape [N_batch, y,x, modes]

TYPE: ndarray

this_obj_chopped

Object slices with shape [N_batch, y,x, z, modes].

TYPE: ndarray

num_slices

Number of object slices.

TYPE: int

n_obj_modes

Number of object modes.

TYPE: int

n_probe_modes

Number of probe modes.

TYPE: int

this_distances

Slice thicknesses.

TYPE: ndarray

this_wavelength

Electron wavelength.

TYPE: float

q2

Spatial frequency grids.

TYPE: ndarray

qx

Spatial frequency grids.

TYPE: ndarray

qy

Spatial frequency grids.

TYPE: ndarray

exclude_mask

Mask to exclude undesired frequencies.

TYPE: ndarray

is_single_dist

If True, use the same distance for all slices.

TYPE: bool

this_tan_x

Beam tilts with shape N_batch

TYPE: ndarray

this_tan_y

Beam tilts with shape N_batch

TYPE: ndarray

damping_cutoff_multislice

Damping frequency cutoff.

TYPE: float

smooth_rolloff

Rolloff rate for the damping filter.

TYPE: float

master_propagator_phase_space

Full propagator in Fourier space (optional).

TYPE: ndarray or None

half_master_propagator_phase_space

Half-step propagator (optional).

TYPE: ndarray or None

mask_clean

Clean propagation mask.

TYPE: ndarray

waves_multislice

This array contains interediate exit-waves

TYPE: ndarray

wave

This array contains final exit-wave

TYPE: ndarray

default_float

Numerical types.

TYPE: dtype

default_complex

Numerical types.

TYPE: dtype

RETURNS DESCRIPTION
waves_multislice

Multislice stack of propagated waves.

TYPE: ndarray

wave

Final exit wave.

TYPE: ndarray

yoshida_multislice_grads

Compute gradients for object, probe, and tilt parameters using Yoshida multislice propagation.

PARAMETER DESCRIPTION
dLoss_dP_out

Gradient of the loss with respect to the output wave.

TYPE: ndarray

waves_multislice

Stored intermediate wavefields from forward Yoshida multislice pass.

TYPE: ndarray

this_obj_chopped

Object slices with shape [batch, y, x, z, modes].

TYPE: ndarray

object_grad

Gradient buffer for object update.

TYPE: ndarray

tilts_grad

Gradient buffer for tilt update.

TYPE: ndarray

is_single_dist

Whether slice distances are constant.

TYPE: bool

this_distances

Thickness of each slice.

TYPE: ndarray

exclude_mask

FFT mask for excluding unstable frequencies.

TYPE: ndarray

this_wavelength

Probe wavelength in Ångströms.

TYPE: float

q2

FFT spatial frequency grids.

TYPE: ndarray

qx

FFT spatial frequency grids.

TYPE: ndarray

qy

FFT spatial frequency grids.

TYPE: ndarray

this_tan_x

Beam tilts (tangent of the angle).

TYPE: float

this_tan_y

Beam tilts (tangent of the angle).

TYPE: float

num_slices

Number of object slices.

TYPE: int

n_probe_modes

Number of probe modes.

TYPE: int

n_obj_modes

Number of object modes.

TYPE: int

tiltind

Index of current tilt in tilts_grad.

TYPE: int

this_step_tilts

Whether tilt updates are enabled.

TYPE: int

master_propagator_phase_space

Full propagation kernel in Fourier domain.

TYPE: ndarray

half_master_propagator_phase_space

Half-step propagation kernel.

TYPE: ndarray

damping_cutoff_multislice

Frequency cutoff for damping high frequencies.

TYPE: float

smooth_rolloff

Rolloff profile width for damping.

TYPE: float

tilt_mode

Determines which tilt parameters to optimize.

TYPE: int

compute_batch

Number of scan points in the current batch.

TYPE: int

mask_clean

Fourier domain mask to stabilize calculations.

TYPE: ndarray

masked_pixels_y

Indices for inserting gradients into global object.

TYPE: ndarray

masked_pixels_x

Indices for inserting gradients into global object.

TYPE: ndarray

default_float

Float precision.

TYPE: dtype

default_complex

Complex precision.

TYPE: dtype

RETURNS DESCRIPTION
object_grad

Updated object gradient.

TYPE: ndarray

interm_probe_grad

Gradient of the probe (combined over object modes).

TYPE: ndarray

tilts_grad

Updated tilt gradient.

TYPE: ndarray

scatteradd

Adds batched object updates to their respective positions in the full object array. This wrapper is needed to support older CuPy versions.

PARAMETER DESCRIPTION
full

Full object gradient array.

TYPE: ndarray

masky

Index array for the y-axis.

TYPE: ndarray

maskx

Index array for the x-axis.

TYPE: ndarray

chop

Batched gradients to scatter-add.

TYPE: ndarray

RETURNS DESCRIPTION
None

pypty.objective - PyPty (python + ptychography)

pypty.objective

loss_and_direction

Compute the total loss and gradients for ptychographic reconstruction.

This is the core function of PyPty that performs forward and backward propagation, calculates the loss between measured and simulated patterns, and computes the gradients of all active reconstruction parameters (object, probe, positions, tilts, etc.).

PARAMETER DESCRIPTION
this_obj

Complex 4D object (current estimate)

TYPE: ndarray

full_probe

Complex probe (y,x,modes) optionally 4D (y,x,modes, scenatios)

TYPE: ndarray

this_pos_array

Integer beam postions in pixels [[y0,x0],.. [yn, xn]]. Note: units are pixels, not angstrom!

TYPE: ndarray

this_pos_correction

Float sub-pixel postions for more precise beam shift. Note: units are pixels, not angstrom!

TYPE: ndarray

this_tilt_array

Beam tilts in radians, shape should be (N_measurements, 6), where first two tilts are applied before the sample, second and third are applied inside (tilted propagator) and two last are applied after the sample

TYPE: ndarray

this_tilts_correction

legacy paramter, actually is not really required. It is a correction that is added to the tilts array.

TYPE: ndarray

this_distances

either just one value for a common slice spacing or list of values for each slice. If object has N slices, it should have N-1 entries.

TYPE: ndarray

measured_array

array or h5-dataset with diffraction patterns. Should be 3D, [N_measurements, y,x]

TYPE: ndarray

algorithm_type

string indicating the loss function (error metric)
this_wavelength

Electron wavelength in Angstrom

TYPE: float

this_step_probe

do you refine the beam?

TYPE: float

this_step_obj

do you refine the object?

TYPE: float

this_step_pos_correction

do you refine the positions?
this_step_tilts

do you refine the tilts?

TYPE: float

masks

optional, if the data is compressed, you should provide the 3D array with virtual detectors [N_detectors, y,x].

TYPE: ndarray

pixel_size_x_A

real-space pixel size in x-direction (Angstrom).

TYPE: float

pixel_size_y_A

real-space pixel size in y-direction (Angstrom).

TYPE: float

recon_type

"far_field" or "near_field". Changes the exit-wave propagation regime.

TYPE: string

Cs

Spherical aberration (Angstrom). Only needed for near-field propagation.

TYPE: float

defocus_array

Array of exit-wave defocus values (Angstrom). Only needed for near-field propagation.

TYPE: ndarray

alpha_near_field

Flux-preserving correction for near-field propagation.

TYPE: float

damping_cutoff_multislice

Cutoff (fraction smaller than 1) beyond which the Fouirer-space is cleaned.

TYPE: float

smooth_rolloff

Smooth rolloff for Fourier masking

TYPE: float

propmethod

string indicating the method for split-step integration

TYPE: string

this_chopped_sequence

sequence of measruement indices used for loss and grad calculation (should be sorted)

TYPE: ndarray

load_one_by_one

boolean flag. should be True for lazy loading.

TYPE: bool

data_multiplier

multiplicative factor applied to data on the fly.

TYPE: int

data_pad

padding factor applied to data on the fly.

TYPE: int

phase_plate_in_h5

path to h5 dataset containing phase plates for each measurement.

TYPE: string

this_loss_weight

weight applied to the main part of the loss

TYPE: float

data_bin

binning factor applied to data on the fly

TYPE: int

data_shift_vector

shift vector in pixels (y,x) applied to data on the fly

TYPE: tuple

upsample_pattern

virtual "decompression" of the data used to enlarge the probe window

TYPE: int

static_background

real-valued array descripting the square root of the static offset on the diffraction patterns.

TYPE: ndarray or float

this_step_static_background

do you refine the static background?

TYPE: float

tilt_mode

flag for tilting

TYPE: int

aberration_marker

TYPE: ndarray

probe_marker

TYPE: ndarray

aberrations_array

TYPE: ndarray

compute_batch

TYPE: int

phase_only_obj

TYPE: bool

beam_current

TYPE: ndarray

this_beam_current_step

TYPE: float

this_step_aberrations_array

TYPE: float

default_float

TYPE: dtype

default_complex

TYPE: dtype

xp

TYPE: module

is_first_epoch

TYPE: bool

scan_size

TYPE: tuple

fast_axis_reg_weight_positions

TYPE: float

slow_axis_reg_weight_positions

TYPE: float

slow_axis_reg_weight_tilts

TYPE: float

current_deformation_reg_weight_positions

TYPE: float

current_deformation_reg_weight_tilts

TYPE: float

fast_axis_reg_weight_tilts

TYPE: float

aperture_mask

TYPE: ndarray

probe_reg_weight

TYPE: float

current_window_weight

TYPE: float

current_window

TYPE: ndarray

phase_norm_weight

TYPE: float

abs_norm_weight

TYPE: float

atv_weight

TYPE: float

atv_q

TYPE: float

atv_p

TYPE: float

mixed_variance_weight

TYPE: float

mixed_variance_sigma

TYPE: float

smart_memory

do you want to prevent memory fragmentation? Makes the reconstrcution slightly slower

TYPE: bool

print_flag

verbodity level

TYPE: int

RETURNS DESCRIPTION
loss

Total loss value.

TYPE: float

sse

Sum of squared errors.

TYPE: float

object_grad

Gradient of the loss with respect to the object.

TYPE: ndarray

probe_grad

Gradient of the loss with respect to the probe.

TYPE: ndarray

pos_grad

Gradient of the loss with respect to scan position corrections.

TYPE: ndarray

tilts_grad

Gradient of the loss with respect to tilts.

TYPE: ndarray

static_background_grad

Gradient of the loss with respect to static background.

TYPE: ndarray

aberrations_array_grad

Gradient of the loss with respect to aberration coefficients.

TYPE: ndarray

beam_current_grad

Gradient of the loss with respect to beam current.

TYPE: ndarray

constraint_contributions

Individual regularization loss terms added to the total loss.

TYPE: list

scatteradd_probe

Adds batched probe updates to their respective positions in the full probe array. This wrapper is needed to support older CuPy version.

PARAMETER DESCRIPTION
full

Full probe gradient array.

TYPE: ndarray

indic

Indices specifying where to add each batch.

TYPE: array_like

batches

Batched gradients to scatter-add.

TYPE: ndarray

scatteradd_abers

Adds batched aberration updates to their respective positions in the full aberration array. This wrapper is needed to support older CuPy version.

PARAMETER DESCRIPTION
full

Full aberration gradient array.

TYPE: ndarray

indic

Indices specifying where to add each batch.

TYPE: array_like

batches

Batched gradients to scatter-add.

TYPE: ndarray

charge_flip

Perform charge-flipping style object regularization to enhance phase and absorption contrast.

PARAMETER DESCRIPTION
a

Complex object to regularize.

TYPE: ndarray

delta_phase

Phase threshold ratio.

TYPE: float DEFAULT: 0.03

delta_abs

Absorption threshold ratio.

TYPE: float DEFAULT: 0.14

beta_phase

Inversion multiplier for low-phase regions.

TYPE: float DEFAULT: -0.95

beta_abs

Inversion multiplier for low-absorption regions.

TYPE: float DEFAULT: -0.95

fancy_sigma

Tuple of atomic-shape gaussian kernel sigmas (for phase, absorption).

TYPE: tuple or None DEFAULT: None

RETURNS DESCRIPTION
ndarray

Regularized complex object.

make_states_orthogonal

Apply Gram-Schmidt orthogonalization to probe modes.

PARAMETER DESCRIPTION
probe_states

Probe array with multiple modes.

TYPE: ndarray

RETURNS DESCRIPTION
ndarray

Orthogonalized probe states.

make_basis_orthogonal

Orthogonalize a set of 1D basis vectors using Gram-Schmidt.

PARAMETER DESCRIPTION
vectors

2D array of vectors to orthogonalize.

TYPE: ndarray

RETURNS DESCRIPTION
ndarray

Orthogonalized basis.

clear_missing_wedge

Remove missing wedge artifacts by applying a cone filter in 3D FFT space.

PARAMETER DESCRIPTION
obj

3D complex object.

TYPE: ndarray

px_size_x_A

Pixel size along x (Å).

TYPE: float

px_size_y_A

Pixel size along y (Å).

TYPE: float

slice_distance

Distance between slices (Å).

TYPE: float

beta_wedge

Cone sharpness parameter.

TYPE: float

RETURNS DESCRIPTION
ndarray

Filtered object with reduced missing wedge effects.

compute_fast_axis_constraint_on_grid

Apply second-order TV regularization along the fast scan axis.

PARAMETER DESCRIPTION
something

Positions or tilts to regularize.

TYPE: ndarray

scan_size

Size of the scan grid.

TYPE: tuple

tv_reg_weight

Regularization weight.

TYPE: float

RETURNS DESCRIPTION
reg_term

Value of the regularization term.

TYPE: float

grad

Gradient of the regularization.

TYPE: ndarray

compute_slow_axis_constraint_on_grid

Apply second-order TV regularization along the slow scan axis.

PARAMETER DESCRIPTION
something

Positions or tilts to regularize.

TYPE: ndarray

scan_size

Size of the scan grid.

TYPE: tuple

tv_reg_weight

Regularization weight.

TYPE: float

RETURNS DESCRIPTION
reg_term

Regularization loss.

TYPE: float

grad

Gradient with respect to the input.

TYPE: ndarray

compute_deformation_constraint_on_grid

Penalize deviations from affine transformations in local scan patches.

PARAMETER DESCRIPTION
something

Grid to regularize (positions or tilts).

TYPE: ndarray

scan_size

Dimensions of the scan.

TYPE: tuple

reg_weight

Regularization weight.

TYPE: float

RETURNS DESCRIPTION
reg_term

Regularization loss.

TYPE: float

grad

Gradient of the loss with respect to the grid.

TYPE: ndarray

compute_full_l1_constraint

Apply L1 norm regularization to the object's phase and absorption.

PARAMETER DESCRIPTION
object

Complex object array.

TYPE: ndarray

abs_norm_weight

Weight for absorption norm.

TYPE: float

phase_norm_weight

Weight for phase norm.

TYPE: float

grad_mask

Mask to restrict gradient computation.

TYPE: ndarray

return_direction

If True, return the gradient.

TYPE: bool

smart_memory

Memory-efficient option.

TYPE: bool

RETURNS DESCRIPTION
reg_term

Regularization loss.

TYPE: float

grad

Gradient if return_direction is True, else None.

TYPE: ndarray or None

compute_window_constraint

Penalize probe values outside a predefined window region in real-space.

PARAMETER DESCRIPTION
to_reg_probe

Complex probe array.

TYPE: ndarray

current_window

Window mask.

TYPE: ndarray

current_window_weight

Weight of the constraint.

TYPE: float

RETURNS DESCRIPTION
reg_term

Window constraint loss.

TYPE: float

reg_grad

Gradient of the loss with respect to the probe.

TYPE: ndarray

compute_probe_constraint

Apply reciprocal space constraint to the probe using an aperture mask. Penalize probe values outside an aperture.

PARAMETER DESCRIPTION
to_reg_probe

Complex probe array.

TYPE: ndarray

aperture

Binary mask or scalar defining aperture radius.

TYPE: ndarray or float

weight

Regularization weight.

TYPE: float

return_direction

If True, return the gradient.

TYPE: bool

RETURNS DESCRIPTION
reg_term

Loss from masked frequency components.

TYPE: float

probe_fft

Gradient of the constraint if requested.

TYPE: ndarray or None

compute_atv_constraint

Apply adaptive total variation (ATV) regularization to the object.

PARAMETER DESCRIPTION
obj

Complex object.

TYPE: ndarray

atv_weight

Regularization weight.

TYPE: float

atv_q

q-norm parameter.

TYPE: float

atv_p

p-norm parameter.

TYPE: float

pixel_size_x_A

Pixel size along x (Å).

TYPE: float

pixel_size_y_A

Pixel size along y (Å).

TYPE: float

atv_grad_mask

Optional gradient mask.

TYPE: ndarray or None

return_direction

If True, return the gradient.

TYPE: bool

smart_memory

If True, use memory-efficient computation.

TYPE: bool

RETURNS DESCRIPTION
reg_term

ATV regularization value.

TYPE: float

dR_dTerm

Gradient with respect to the object.

TYPE: ndarray

compute_missing_wedge_constraint

Enforce missing wedge constraint in 3D reciprocal space.

PARAMETER DESCRIPTION
obj

3D complex object.

TYPE: ndarray

px_size_x_A

Pixel size along x (Å).

TYPE: float

px_size_y_A

Pixel size along y (Å).

TYPE: float

slice_distance

Slice spacing (Å).

TYPE: float

beta_wedge

Cone sharpness.

TYPE: float

wegde_mu

Regularization weight.

TYPE: float

RETURNS DESCRIPTION
loss_term

Regularization loss.

TYPE: float

grad_obj

Gradient of the loss with respect to the object.

TYPE: ndarray

compute_mixed_object_variance_constraint

Regularize variance across object modes by penalizing their differences.

PARAMETER DESCRIPTION
this_obj

Complex object array with multiple modes.

TYPE: ndarray

weight

Regularization strength.

TYPE: float

sigma

Smoothing kernel width in frequency space.

TYPE: float

return_direction

If True, return the gradient.

TYPE: bool

smart_memory

Use memory-efficient FFT loops.

TYPE: bool

RETURNS DESCRIPTION
reg_term

Mixed variance loss.

TYPE: float

grad

Gradient with respect to the object if return_direction is True.

TYPE: ndarray or None

pypty.se - PyPty (python + ptychography)

pypty.se

getvirtualhaadf

Compute a virtual HAADF image from a 4D-STEM dataset.

PARAMETER DESCRIPTION
pypty_params

Dictionary containing parameters including data path, scan size, plotting option, and output folder.

TYPE: dict

save

Whether to save the resulting HAADF image as a .npy file. Default is True.

TYPE: bool DEFAULT: True

RETURNS DESCRIPTION
haadf

The computed virtual HAADF image.

TYPE: ndarray

get_aperture

Generate a binary aperture mask based on the mean diffraction pattern.

PARAMETER DESCRIPTION
params

Dictionary containing parameters including data path, data padding, plotting option, and bright threshold.

TYPE: dict

RETURNS DESCRIPTION
params

Updated parameters dictionary containing the generated aperture mask.

TYPE: dict

create_binned_dataset

Downsample a dataset by spatial binning and save it to a new file.

PARAMETER DESCRIPTION
path_orig

The file path of the original dataset.

TYPE: str

path_new

The file path to save the binned dataset.

TYPE: str

bin

The binning factor to downsample the dataset.

TYPE: int

compensate_pattern_drift

Compensate for drift in diffraction patterns via phase correlation.

PARAMETER DESCRIPTION
aperture

The binary aperture mask used for phase correlation.

TYPE: ndarray

patterns

The diffraction patterns to be compensated for drift.

TYPE: ndarray

RETURNS DESCRIPTION
patterns

The compensated diffraction patterns.

TYPE: ndarray

get_virtual_annular_detector

Create virtual detector signals from annular masks.

PARAMETER DESCRIPTION
pypty_params

Dictionary containing parameters including data path, scan size, plotting option, and output folder.

TYPE: dict

inner_rad

Inner radius of the annular mask. Default is 0.

TYPE: float DEFAULT: 0

outer_rad

Outer radius of the annular mask. Default is 1.

TYPE: float DEFAULT: 1

save

Whether to save the resulting virtual detector signal as a .npy file. Default is False.

TYPE: bool DEFAULT: False

offset_x

X-offset for the annular mask. Default is 0.

TYPE: float DEFAULT: 0

offset_y

Y-offset for the annular mask. Default is 0.

TYPE: float DEFAULT: 0

RETURNS DESCRIPTION
signal

The computed virtual detector signal.

TYPE: ndarray

pypty.tcbf - PyPty (python + ptychography)

pypty.tcbf

run_tcbf_alignment

Align and fit the beam contrast transfer function (CTF) using 4D-STEM data.

This function estimates beam aberrations by aligning individual pixel images using cross-correlation and fitting a CTF model. It supports iterative fitting with various binning levels and options for low-frequency drift compensation.

PARAMETER DESCRIPTION
params

Dictionary containing PyPTY experimental and reconstruction settings.
binning_for_fit

List (for integers) of binning factors for each iteration of the CTF fit.

TYPE: list DEFAULT: [8]

save

Whether to save intermediate tcBF images and shift estimates.

TYPE: bool DEFAULT: True

optimize_angle

Whether to include probe rotation angle in the fit.

TYPE: bool DEFAULT: True

aberrations

Initial guess for aberrations. If None, n_aberrations_to_fit zeros will be used.

TYPE: list DEFAULT: None

n_aberrations_to_fit

Number of aberrations to fit if no initial guess is provided.

TYPE: int DEFAULT: 12

reference_type

Reference used for cross-correlation ("bf" or "zero").

TYPE: string DEFAULT: 'bf'

refine_box_dim

Radius (in pixels) of the interpolation box for sub-pixel shift refinement.

TYPE: int DEFAULT: 10

upsample

Factor for refining cross-correlation to estimate sub-pixel shifts.

TYPE: int DEFAULT: 3

cross_corr_type

Type of cross-correlation to use ("phase" or "classical").

TYPE: str DEFAULT: 'phase'

cancel_large_shifts

Threshold (0–1) to ignore large shift outliers in the fit.

TYPE: float DEFAULT: None

pattern_blur_width

Radius for optional circular blur mask applied to patterns.

TYPE: int DEFAULT: None

scan_pad

Number of scan pixels to pad around the dataset (auto if None).

TYPE: int DEFAULT: None

aperture

Aperture mask. If None, attempts to extract from parameters.

TYPE: ndarray DEFAULT: None

subscan_region

Subregion for CTF fitting: [left, top, right, bottom].

TYPE: list DEFAULT: None

compensate_lowfreq_drift

Whether to compensate for pattern drift in large FOVs.

TYPE: bool DEFAULT: False

append_lowfreq_shifts_to_params

Whether to store low-frequency drift corrections in params.

TYPE: bool DEFAULT: True

interpolate_scan_factor

Factor to upsample the scan via interpolation (experimental).

TYPE: int DEFAULT: 1

binning_cross_corr

Binning factor before peak detection in cross-correlation.

TYPE: int DEFAULT: 1

phase_cross_corr_formula

Use analytical peak refinement formula for phase correlation.

TYPE: bool DEFAULT: False

f_scale_lsq

Scaling factor for residuals in least_squares.

TYPE: float DEFAULT: 1

x_scale_lsq

Scaling for initial step size in least_squares.

TYPE: float DEFAULT: 1

loss_lsq

Loss function for least_squares optimization.

TYPE: string DEFAULT: 'linear'

tol_ctf

Tolerance (ftol) for stopping criterion in optimization.

TYPE: float DEFAULT: 1e-08

RETURNS DESCRIPTION
dict

Updated parameter dictionary with fitted aberrations, defocus, and potentially updated scan positions and rotation.

upsampled_tcbf

Perform an upsampled tcBF (transmission coherent Bright Field) reconstruction.

This function reconstructs a tcBF image on an upsampled scan grid from 4D-STEM data. It applies Fourier-based shifts to align the bright field pixel images and combines them into a final image. Prior to calling this function, it is recommended to run the tcBF alignment routine to update pypty_params.

PARAMETER DESCRIPTION
pypty_params

Dictionary containing experimental parameters and reconstruction settings. This should include keys such as 'data_path', 'scan_size', 'aperture_mask', 'acc_voltage', etc.

TYPE: dict

upsample

Upsampling factor for the scan grid. Default is 5.

TYPE: int DEFAULT: 5

pad

Number of additional scan positions to pad on each side to avoid wrap-around artifacts. Default is 10.

TYPE: int DEFAULT: 10

compensate_lowfreq_drift

If True, compensates for low-frequency drift of the aperture. Requires that run_tcbf_alignment has been executed to provide drift corrections. Default is False.

TYPE: bool DEFAULT: False

default_float

Precision for floating point computations. Use 64 for higher precision or 32 for lower memory usage. Default is 64.

TYPE: (64, 32) DEFAULT: 64

round_shifts

If True, shifts are rounded and alignment is performed using array roll operations. If False, FFT-based subpixel shifting is used. Default is False.

TYPE: bool DEFAULT: False

xp

Backend array module (e.g., numpy or cupy). Default is cupy.

TYPE: module DEFAULT: numpy

save

Flag to save the output image. If True, the image is saved to disk. Ignored if 'save_preprocessing_files' is set in pypty_params. Default is 0 (False).

TYPE: bool or int DEFAULT: 0

max_parallel_fft

Maximum number of FFTs to perform in parallel for vectorized processing. Default is 100.

TYPE: int DEFAULT: 100

bin_fac

Binning factor for the data in reciprocal space. Default is 1 (no binning).

TYPE: int DEFAULT: 1

RETURNS DESCRIPTION
ndarray

Real-valued tcBF image reconstructed on the upsampled grid.
float

Final pixel size in Ångströms after upsampling.

run_tcbf_compressed_alignment

Perform a CTF alignment using compressed 4D-STEM data and masked bright-field regions.

This function fits the beam CTF to the shifts between the individual pixel images of the 4d-stem dataset. It's the same as run_tcbf_alignment, but for compressed data. The shift estimation is done via cross-correaltion.

PARAMETER DESCRIPTION
params

Dictionary containing experimental and reconstruction settings.

TYPE: dict

num_iterations

Number of fitting iterations to perform.

TYPE: int

save

Whether to save intermediate tcBF images and shift maps. Default is True.

TYPE: bool DEFAULT: True

optimize_angle

Whether to include probe rotation angle in the CTF fit. Default is True.

TYPE: bool DEFAULT: True

aberrations

Initial guess for the aberration coefficients. If None, it will be inferred or zero-initialized.

TYPE: list or None DEFAULT: None

n_aberrations_to_fit

Number of aberration coefficients to fit if aberrations is not provided. Default is 12.

TYPE: int DEFAULT: 12

reference_type

"bf" to use the tcBF image as a reference, "zero" to use the central pixel. Default is "bf".

TYPE: str DEFAULT: 'bf'

refine_box_dim

Size of the cropped region around the cross-correlation peak for sub-pixel refinement. Default is 10.

TYPE: int DEFAULT: 10

upsample

Upsampling factor for sub-pixel interpolation. Default is 3.

TYPE: int DEFAULT: 3

cross_corr_type

Cross-correlation method: "phase" (recommended) or "classic". Default is "phase".

TYPE: str DEFAULT: 'phase'

cancel_large_shifts

Threshold to reject large shift outliers during fitting. Value between 0 and 1. Default is None.

TYPE: float or None DEFAULT: None

pattern_blur_width

Width of blur kernel for patterns prior to analysis. Default is None.

TYPE: int or None DEFAULT: None

scan_pad

Number of scan pixels to pad around the scan to prevent wrap-around. Default is auto.

TYPE: int or None DEFAULT: None

aperture

Aperture mask defining pixels to analyze. If None, it will be loaded from params.

TYPE: ndarray or None DEFAULT: None

subscan_region

Optional subregion [left, top, right, bottom] on which to perform the alignment. Default is None.

TYPE: list or None DEFAULT: None

compensate_lowfreq_drift

Whether to compute and correct for slow drifting of the aperture over time. Default is False.

TYPE: bool DEFAULT: False

append_lowfreq_shifts_to_params

If True, saves the low-frequency correction back into params. Default is True.

TYPE: bool DEFAULT: True

interpolate_scan_factor

Experimental: interpolate scan grid by this factor (e.g., 2 for 2x upsampled grid). Default is 1.

TYPE: int DEFAULT: 1

binning_cross_corr

Binning factor applied to cross-correlation maps before refinement. Default is 1.

TYPE: int DEFAULT: 1

phase_cross_corr_formula

If True, uses analytical subpixel peak estimation for phase correlation. Default is False.

TYPE: bool DEFAULT: False

f_scale_lsq

Scaling factor for least squares residuals (f_scale). Default is 1.

TYPE: float DEFAULT: 1

x_scale_lsq

Initial step scaling (x_scale) for least squares. Default is 1.

TYPE: float DEFAULT: 1

loss_lsq

Loss type for least squares optimizer. E.g., "linear", "huber". Default is "linear".

TYPE: str DEFAULT: 'linear'

tol_ctf

Tolerance for optimizer convergence (ftol). Default is 1e-8.

TYPE: float DEFAULT: 1e-08

RETURNS DESCRIPTION
dict

Updated dictionary of reconstruction parameters including fitted aberrations and scan rotation.

pypty.utils - PyPty (python + ptychography)

pypty.utils

fourier_clean_3d

Apply a 3D Fourier filter to the input array.

PARAMETER DESCRIPTION
array

Input 3D array to be filtered.

TYPE: array_like

cutoff

Cutoff frequency (default is 0.66).

TYPE: float DEFAULT: 0.66

mask

Predefined mask to apply. If None, a mask is generated.

TYPE: array_like or None DEFAULT: None

rolloff

Rolloff parameter for smoothing the mask (default is 0).

TYPE: float DEFAULT: 0

default_float

Data type for computations (default is cp.float32).

TYPE: data - type DEFAULT: float32

xp

Array module (default is cp).

TYPE: module DEFAULT: numpy

RETURNS DESCRIPTION
array_like

The filtered array after applying the Fourier filter.

fourier_clean

Apply a Fourier filter to the input array. Supports 2D or 3D arrays.

PARAMETER DESCRIPTION
array

Input array (2D or 3D) to be filtered.

TYPE: array_like

cutoff

Cutoff frequency (default is 0.66).

TYPE: float DEFAULT: 0.66

mask

Predefined mask to apply. If None, a mask is generated.

TYPE: array_like or None DEFAULT: None

rolloff

Rolloff parameter for smoothing the mask (default is 0).

TYPE: float DEFAULT: 0

default_float

Data type for computations (default is cp.float32).

TYPE: data - type DEFAULT: float32

xp

Array module (default is cp).

TYPE: module DEFAULT: numpy

RETURNS DESCRIPTION
array_like

The filtered array after applying the Fourier filter.

create_spatial_frequencies

Generate spatial frequency grids and corresponding masks for multislice simulations.

PARAMETER DESCRIPTION
px

Pixel size in the x-direction.

TYPE: float

py

Pixel size in the y-direction.

TYPE: float

shape

Size of the grid.

TYPE: int

damping_cutoff_multislice

Damping cutoff factor for multislice simulations.

TYPE: float

smooth_rolloff

Smoothing rolloff parameter.

TYPE: float

default_float

Data type for computations.

TYPE: data - type

RETURNS DESCRIPTION
tuple

Tuple containing: - q2: 2D array of squared spatial frequencies. - qx: 2D array of spatial frequencies in x. - qy: 2D array of spatial frequencies in y. - exclude_mask: Mask in Fourier space. - exclude_mask_ishift: Unshifted mask.

shift_probe_fourier

Shift a probe in Fourier space by applying a phase ramp.

PARAMETER DESCRIPTION
probe

The input probe array.

TYPE: array_like

shift_px

Shift in pixels (y, x).

TYPE: tuple of float

RETURNS DESCRIPTION
tuple

Tuple containing the shifted probe, the phase mask, the Fourier transform of the probe, and the spatial frequency grids (maskx, masky).

generate_mask_for_grad_from_pos

Construct a binary mask from given positions and footprint dimensions.

PARAMETER DESCRIPTION
shapex

Width of the mask.

TYPE: int

shapey

Height of the mask.

TYPE: int

positions_list

List of (y, x) positions where the mask should be activated.

TYPE: list of tuple

shape_footprint_x

Footprint width.

TYPE: int

shape_footprint_y

Footprint height.

TYPE: int

shrink

Shrink factor to adjust the footprint (default is 0).

TYPE: int DEFAULT: 0

RETURNS DESCRIPTION
array_like

The constructed binary mask.

complex_grad_to_phase_grad

Convert a Wirtinger derivative to the gradient with respect to the phase.

PARAMETER DESCRIPTION
grad

The Wirtinger derivative (dL/dz*).

TYPE: array_like

array

The complex array (z = |z| exp(i*phase)).

TYPE: array_like

RETURNS DESCRIPTION
array_like

The phase gradient (dL/dp).

complex_grad_to_phase_abs_grad

Compute the phase gradient and negative amplitude gradient from a complex gradient.

PARAMETER DESCRIPTION
grad

The Wirtinger derivative (dL/dz*).

TYPE: array_like

array

The complex array (z = exp(-a + i*phase)).

TYPE: array_like

RETURNS DESCRIPTION
tuple of array_like

A tuple containing: - Phase gradient (dL/dp). - Negative amplitude gradient (dL/da).

complex_grad_to_mag_grad

Calculate a magnitude gradient from a complex gradient and separate magnitude and phase arrays.

PARAMETER DESCRIPTION
grad

The complex gradient.

TYPE: array_like

abs

The magnitude array.

TYPE: array_like

phase

The phase array.

TYPE: array_like

RETURNS DESCRIPTION
array_like

The magnitude gradient.

construct_update_abs_proto_phase

Compute object updates projected along phase gradients.

PARAMETER DESCRIPTION
object_grad

The gradient of the object.

TYPE: array_like

obj

The current object array.

TYPE: array_like

RETURNS DESCRIPTION
array_like

The computed update for the object.

wolfe_1

Check the Armijo condition (Wolfe condition 1) for line search.

PARAMETER DESCRIPTION
value

The current function value.

TYPE: float

new_value

The function value after the step.

TYPE: float

d_value

The directional derivative at the current point.

TYPE: float

step

Step size.

TYPE: float

wolfe_c1

Armijo condition constant (default is 0.5).

TYPE: float DEFAULT: 0.5

RETURNS DESCRIPTION
bool

True if the condition is satisfied, False otherwise.

wolfe_2

Check the curvature condition (Wolfe condition 2) for line search.

PARAMETER DESCRIPTION
d_value

The directional derivative at the current point.

TYPE: float

new_d_value

The directional derivative after the step.

TYPE: float

wolfe_c2

Curvature condition constant (default is 0.9).

TYPE: float DEFAULT: 0.9

RETURNS DESCRIPTION
bool

True if the condition is satisfied, False otherwise.

upsample_something_3d

Upsample a 3D array along the last two axes.

PARAMETER DESCRIPTION
something

The 3D array to be upsampled.

TYPE: ndarray

upsample

Upsampling factor.

TYPE: int

scale

If True, scales the upsampled result to conserve total sum (default is True).

TYPE: bool DEFAULT: True

xp

Array module, e.g., numpy or cupy (default is numpy).

TYPE: module DEFAULT: numpy

RETURNS DESCRIPTION
ndarray

The upsampled 3D array.

downsample_something_3d

Downsample a 3D array along the last two axes.

PARAMETER DESCRIPTION
something

The 3D array to be downsampled.

TYPE: ndarray

upsample

Downsampling factor.

TYPE: int

xp

Array module, e.g., numpy or cupy.

TYPE: module

RETURNS DESCRIPTION
ndarray

The downsampled 3D array.

upsample_something

Upsample a 2D array.

PARAMETER DESCRIPTION
something

The 2D array to be upsampled.

TYPE: ndarray

upsample

Upsampling factor.

TYPE: int

scale

If True, scales the result to conserve total sum (default is True).

TYPE: bool DEFAULT: True

xp

Array module (default is numpy).

TYPE: module DEFAULT: numpy

RETURNS DESCRIPTION
ndarray

The upsampled array.

downsample_something

Downsample a 2D array.

PARAMETER DESCRIPTION
something

The 2D array to be downsampled.

TYPE: ndarray

upsample

Downsampling factor.

TYPE: int

xp

Array module, e.g., numpy or cupy.

TYPE: module

RETURNS DESCRIPTION
ndarray

The downsampled array.

preprocess_dataset

Apply preprocessing steps to the dataset including shifting, binning, padding, and scaling.

PARAMETER DESCRIPTION
dataset

The input dataset.

TYPE: ndarray

load_one_by_one

Whether data is loaded incrementally.

TYPE: bool

algorithm_type

Type of reconstruction algorithm.

TYPE: str

recon_type

Type of reconstruction (e.g., near_field, far_field).

TYPE: str

data_shift_vector

Vector indicating pixel shift in y and x.

TYPE: list of int

data_bin

Binning factor.

TYPE: int

data_pad

Padding size.

TYPE: int

upsample_pattern

Upsampling factor for the pattern.

TYPE: int

data_multiplier

Factor to scale data intensity.

TYPE: float

xp

Array module, e.g., numpy or cupy.

TYPE: module

force_pad

If True, apply forced padding.

TYPE: bool

RETURNS DESCRIPTION
tuple

Tuple containing: - preprocessed dataset - data_shift_vector - data_bin - data_pad - data_multiplier

get_window

Create a circular cosine-tapered window mask.

PARAMETER DESCRIPTION
shape

Size of the square window.

TYPE: int

r0

Inner radius where tapering begins (normalized).

TYPE: float

r_max

Outer radius where mask falls to zero (normalized).

TYPE: float

inverted

If True, returns 1 - mask (default is True).

TYPE: bool DEFAULT: True

RETURNS DESCRIPTION
ndarray

A 2D mask array of the specified shape.

convert_num_to_nmab

Convert a number of aberration terms to (n, m, ab) indices based on Krivanek notation.

PARAMETER DESCRIPTION
num_abs

Number of aberration coefficients.

TYPE: int

RETURNS DESCRIPTION
tuple of lists

Lists of n, m, and ab strings ('', 'a', or 'b') for each aberration mode.

nmab_to_strings

Convert aberration indices into string identifiers in Krivanek notation.

PARAMETER DESCRIPTION
possible_n

List of radial indices.

TYPE: list of int

possible_m

List of azimuthal indices.

TYPE: list of int

possible_ab

List of aberration mode types ('', 'a', 'b').

TYPE: list of str

RETURNS DESCRIPTION
list of str

List of formatted aberration identifiers like 'C30a', 'C11', etc.

get_ctf_matrix

Generate a matrix of phase contributions for all aberration modes.

PARAMETER DESCRIPTION
kx

Spatial frequency in x-direction.

TYPE: ndarray

ky

Spatial frequency in y-direction.

TYPE: ndarray

num_abs

Number of aberration coefficients.

TYPE: int

wavelength

Electron wavelength.

TYPE: float

xp

Array module (default is cupy).

TYPE: module DEFAULT: numpy

RETURNS DESCRIPTION
ndarray

list of Zernike polynomials (num_abs, height, width) with phase contributions.

get_ctf

Compute the scalar contrast transfer function (CTF) from aberrations.

PARAMETER DESCRIPTION
aberrations

List of aberration coefficients.

TYPE: list or ndarray

kx

Spatial frequency in x-direction.

TYPE: ndarray

ky

Spatial frequency in y-direction.

TYPE: ndarray

wavelength

Electron wavelength.

TYPE: float

angle_offset

Additional rotation angle in radians (default is 0).

TYPE: float DEFAULT: 0

RETURNS DESCRIPTION
ndarray

The computed CTF.

get_ctf_derivatives

Compute spatial derivatives of the CTF with respect to kx and ky.

PARAMETER DESCRIPTION
aberrations

List of aberration coefficients.

TYPE: list or ndarray

kx

Spatial frequency in x-direction.

TYPE: ndarray

ky

Spatial frequency in y-direction.

TYPE: ndarray

wavelength

Electron wavelength.

TYPE: float

angle_offset

Additional rotation angle (default is 0).

TYPE: float DEFAULT: 0

RETURNS DESCRIPTION
tuple of ndarray

Derivatives of CTF with respect to kx and ky.

get_ctf_gradient_rotation_angle

Compute the gradient of the phase with respect to rotation angle.

PARAMETER DESCRIPTION
aberrations

List of aberration coefficients.

TYPE: list or ndarray

kx

Spatial frequency in x-direction.

TYPE: ndarray

ky

Spatial frequency in y-direction.

TYPE: ndarray

wavelength

Electron wavelength.

TYPE: float

angle_offset

Additional angular offset (default is 0).

TYPE: float DEFAULT: 0

RETURNS DESCRIPTION
tuple of ndarray

Derivatives of the CTF gradient in x and y directions with respect to angular change.

apply_defocus_probe

Apply a defocus phase shift to a probe in Fourier space.

PARAMETER DESCRIPTION
probe

The input probe wavefunction.

TYPE: ndarray

distance

Defocus distance in meters.

TYPE: float

acc_voltage

Acceleration voltage in kiloelectronvolts (keV).

TYPE: float

pixel_size_x_A

Pixel size along x in angstroms.

TYPE: float

pixel_size_y_A

Pixel size along y in angstroms.

TYPE: float

default_complex

Complex data type for computation.

TYPE: dtype

default_float

Float data type for computation.

TYPE: dtype

xp

Numerical backend (NumPy or CuPy).

TYPE: module

RETURNS DESCRIPTION
ndarray

The defocused probe.

padfft

Pad the input array in Fourier space by padding its FFT.

PARAMETER DESCRIPTION
array

Input array to be padded.

TYPE: ndarray

pad

Number of pixels to pad on each side.

TYPE: int

RETURNS DESCRIPTION
ndarray

The padded array in spatial domain.

padprobetodatafarfield

Pad or crop a probe in Fourier space to match far-field data dimensions.

PARAMETER DESCRIPTION
probe

The probe wavefunction.

TYPE: ndarray

measured_data_shape

Shape of the measured data.

TYPE: tuple

data_pad

Padding applied to the data.

TYPE: int

upsample_pattern

Upsampling factor used in the reconstruction.

TYPE: int

RETURNS DESCRIPTION
ndarray

Adjusted probe wavefunction.

padprobetodatanearfield

Pad or crop a probe for near-field reconstruction.

This function adjusts the probe wavefunction by padding or cropping it to match the near-field measured data dimensions after upsampling and padding.

PARAMETER DESCRIPTION
probe

The input probe wavefunction.

TYPE: ndarray

measured_data_shape

Shape of the measured data.

TYPE: tuple

data_pad

Padding size applied to the data.

TYPE: int

upsample_pattern

Upsampling factor applied to the measured data.

TYPE: int

RETURNS DESCRIPTION
ndarray

The adjusted probe wavefunction.

save_updated_arrays

Save current reconstruction state and log loss metrics during training.

This function saves checkpoints for object, probe, tilts, scan positions, static background, aberration coefficients, and beam current if specified. It also logs loss and constraint contributions in a CSV file if logging is enabled.

PARAMETER DESCRIPTION
output_folder

Directory where files will be saved.

TYPE: str

epoch

Current epoch number.

TYPE: int

current_probe_step

Whether to save the current probe.

TYPE: bool

current_probe_pos_step

Whether to save current scan positions.

TYPE: bool

current_tilts_step

Whether to save current tilts.

TYPE: bool

current_obj_step

Whether to save the current object.

TYPE: bool

obj

Object array to save.

TYPE: ndarray or ndarray

probe

Probe array to save.

TYPE: ndarray or ndarray

tilts_correction

Tilt correction values.

TYPE: ndarray

full_pos_correction

Sub-pixel scan position correction.

TYPE: ndarray

positions

Integer scan positions.

TYPE: ndarray

tilts

Original tilt values.

TYPE: ndarray

static_background

Static background array.

TYPE: ndarray or ndarray

current_aberrations_array_step

Whether to save aberration array.

TYPE: bool

current_static_background_step

Whether to save static background.

TYPE: bool

count

Not used inside the function.

TYPE: int

current_loss

Current loss value.

TYPE: float

current_sse

Current sum of squared errors.

TYPE: float

aberrations

Array of aberration coefficients.

TYPE: ndarray or ndarray

beam_current

Array of beam current values.

TYPE: ndarray or ndarray

current_beam_current_step

Whether to save beam current.

TYPE: bool

save_flag

Whether to trigger checkpoint saving.

TYPE: bool

save_loss_log

Whether to log loss. If set to 2, log full breakdown of constraints.

TYPE: bool or int

constraint_contributions

List of constraint term contributions to the loss.

TYPE: list

actual_step

Step size applied in the optimizer.

TYPE: float

count_linesearch

Number of line search iterations.

TYPE: int

d_value

Initial directional derivative.

TYPE: float

new_d_value

New directional derivative after the step.

TYPE: float

current_update_step_bfgs

Step size suggested by BFGS or optimizer.

TYPE: float

t0

Start time of the epoch (used for timing).

TYPE: float

xp

NumPy or CuPy module used for computation.

TYPE: module

warnings

Warning string to be logged.

TYPE: str

RETURNS DESCRIPTION
None

create_static_background_from_nothing

Generate an initial static background if none is provided.

PARAMETER DESCRIPTION
static_background

Initial static background value or None.

TYPE: float or ndarray

probe

Probe wavefunction.

TYPE: ndarray

damping_cutoff_multislice

Maximum spatial frequency used.

TYPE: float

data_pad

Padding to be applied.

TYPE: int

upsample_pattern

Upsampling factor used.

TYPE: int

default_float

Data type for output.

TYPE: dtype

recon_type

Type of reconstruction ('near_field' or 'far_field').

TYPE: str

RETURNS DESCRIPTION
ndarray

Initialized static background.

create_probe_from_nothing

Generate an initial probe guess when no valid probe is provided.

Depending on the input, this function either uses an aperture mask, computes a mean pattern from the dataset, or adjusts an existing mean pattern to generate a probe. It applies shifting, binning, padding, and scaling to produce a probe suitable for the specified reconstruction type.

PARAMETER DESCRIPTION
probe

Input probe. If set to "aperture", the aperture mask is used. If None, the probe is generated based on the mean pattern.

TYPE: ndarray, str, or None

data_pad

Padding size applied to the data.

TYPE: int

mean_pattern

Mean pattern used to generate the probe if no probe is provided.

TYPE: ndarray or None

aperture_mask

Aperture mask used when probe is set to "aperture".

TYPE: ndarray

tilt_mode

Flag indicating if tilt mode is active.

TYPE: bool

tilts

Tilt values.

TYPE: ndarray

dataset

Measured dataset.

TYPE: ndarray

estimate_aperture_based_on_binary

Factor used to threshold the dataset for aperture estimation.

TYPE: bool or float

pixel_size_x_A

Pixel size in the x-direction in angstroms.

TYPE: float

acc_voltage

Acceleration voltage in keV.

TYPE: float

data_multiplier

Factor to scale the data intensity.

TYPE: float

masks

Optional masks to apply to the mean pattern.

TYPE: ndarray or None

data_shift_vector

Vector indicating the shift to be applied to the data.

TYPE: list or tuple of int

data_bin

Binning factor.

TYPE: int

upsample_pattern

Upsampling factor applied to the pattern.

TYPE: int

default_complex_cpu

Complex data type for CPU computations.

TYPE: dtype

print_flag

Flag controlling verbosity.

TYPE: int

algorithm

Identifier for the reconstruction algorithm.

TYPE: str

measured_data_shape

Shape of the measured data.

TYPE: tuple

n_obj_modes

Number of object modes.

TYPE: int

probe_marker

Marker array for probe scenarios.

TYPE: ndarray or None

recon_type

Type of reconstruction ("near_field" or "far_field").

TYPE: str

defocus_array

Array of defocus values.

TYPE: ndarray

Cs

Spherical aberration coefficient.

TYPE: float

RETURNS DESCRIPTION
ndarray

The generated probe as a complex array.

generate_hermite_modes

Generate Hermite polynomial-based probe modes from a main mode.

PARAMETER DESCRIPTION
main_mode

The main probe mode.

TYPE: ndarray

n_herm_x

Max Degree of Hermite polynomials in x.

TYPE: int

n_herm_y

Max Degree of Hermite polynomials in y.

TYPE: int

default_complex

Complex data type to use.

TYPE: dtype

xp

Numerical backend.

TYPE: module

RETURNS DESCRIPTION
ndarray

Stack of Hermite-based probe modes.

apply_probe_modulation

Apply defocus, aberrations, Hermite mode generation, and other modulations to the probe.

PARAMETER DESCRIPTION
probe

Initial probe.

TYPE: ndarray

extra_probe_defocus

Defocus distance to apply.

TYPE: float

acc_voltage

Accelerating voltage in keV.

TYPE: float

pixel_size_x_A

Pixel size in x (Å).

TYPE: float

pixel_size_y_A

Pixel size in y (Å).

TYPE: float

aberrations

List of aberration coefficients.

TYPE: list or ndarray

print_flag

Whether to print info.

TYPE: bool

beam_ctf

Optional beam CTF to apply.

TYPE: ndarray or None

n_hermite_probe_modes

Number of Hermite modes in (y, x).

TYPE: tuple or None

defocus_spread_modes

Defocus values to generate additional modes.

TYPE: list or None

probe_marker

Probe assignment array for multi-scenario.

TYPE: ndarray or None

default_complex

Complex type.

TYPE: dtype

default_float

Float type.

TYPE: dtype

xp

Numerical backend.

TYPE: module

RETURNS DESCRIPTION
ndarray

Modulated probe array.

prepare_main_loop_params

Prepare main loop parameters for reconstruction.

This function adjusts scan positions, pads the object if necessary, handles subpixel corrections, and computes the electron wavelength based on the accelerating voltage.

PARAMETER DESCRIPTION
algorithm

Identifier for the reconstruction algorithm.

TYPE: any

probe

The probe array.

TYPE: ndarray

obj

The object array.

TYPE: ndarray

positions

Array of scan positions.

TYPE: ndarray

tilts

Array of tilt angles.

TYPE: ndarray

measured_data_shape

Shape of the measured data.

TYPE: tuple

acc_voltage

Accelerating voltage in keV.

TYPE: float

allow_subPixel_shift

If True, compute subpixel corrections (default is True).

TYPE: bool DEFAULT: True

sequence

Sequence of indices for positions (default is None, which uses full range).

TYPE: list or callable DEFAULT: None

use_full_FOV

If True, use full field-of-view adjustments (default is False).

TYPE: bool DEFAULT: False

print_flag

Verbosity flag (default is 0).

TYPE: int DEFAULT: 0

default_float_cpu

Float data type for CPU computations (default is np.float64).

TYPE: data - type DEFAULT: float64

default_complex_cpu

Complex data type for CPU computations (default is np.complex128).

TYPE: data - type DEFAULT: complex128

default_int_cpu

Integer data type for CPU computations (default is np.int64).

TYPE: data - type DEFAULT: int64

probe_constraint_mask

Optional mask for probe constraints.

TYPE: ndarray or None DEFAULT: None

aperture_mask

Optional aperture mask.

TYPE: ndarray or None DEFAULT: None

extra_space_on_side_px

Extra padding (in pixels) to add to scan positions (default is 0).

TYPE: int DEFAULT: 0

RETURNS DESCRIPTION
tuple

A tuple containing: - obj : ndarray The padded object array. - positions : ndarray Adjusted (rounded) scan positions. - int A placeholder zero (reserved for future use). - sequence : list The sequence of indices used. - wavelength : float Computed electron wavelength in angstroms. - full_pos_correction : ndarray Subpixel corrections for scan positions. - tilts_correction : ndarray Array of zeros with same shape as tilts (tilt corrections). - aperture_mask : ndarray or None The probe constraint mask or aperture mask if provided.

prepare_saving_stuff

Prepare folder and loss CSV for saving training logs.

PARAMETER DESCRIPTION
output_folder

Directory for results.

TYPE: str

save_loss_log

Whether to save loss values.

TYPE: bool

epoch_prev

Previous epoch index.

TYPE: int

RETURNS DESCRIPTION
None

print_pypty_header

Print formatted header announcing start of reconstruction.

PARAMETER DESCRIPTION
data_path

Path to the dataset.

TYPE: str

output_folder

Directory where results are saved.

TYPE: str

save_loss_log

Whether loss logging is enabled.

TYPE: bool

RETURNS DESCRIPTION
None

save_current_checkpoint_obj_probe

Save intermediate reconstruction data as checkpoints.

This function saves the current state of the object, probe, tilt corrections, scan positions, static background, and aberrations to disk. It is intended to allow resuming reconstruction from the last checkpoint.

PARAMETER DESCRIPTION
output_folder

Directory where checkpoint files will be saved.

TYPE: str

obj

The current object array.

TYPE: ndarray or GPU array

probe

The current probe array.

TYPE: ndarray or GPU array

tilts_correction

Correction values for tilt angles.

TYPE: ndarray

full_pos_correction

Sub-pixel correction values for scan positions.

TYPE: ndarray

positions

Scan positions array.

TYPE: ndarray

tilts

Tilt angles array.

TYPE: ndarray

static_background

Static background array.

TYPE: ndarray

current_probe_step

Flag indicating whether to save the probe.

TYPE: bool

current_obj_step

Flag indicating whether to save the object.

TYPE: bool

current_probe_pos_step

Flag indicating whether to save the scan positions.

TYPE: bool

current_tilts_step

Flag indicating whether to save the tilt angles.

TYPE: bool

current_static_background_step

Flag indicating whether to save the static background.

TYPE: bool

current_aberrations_array_step

Flag indicating whether to save the aberrations array.

TYPE: bool

aberrations_array

The current aberrations array.

TYPE: ndarray or GPU array

beam_current

The current beam current array.

TYPE: ndarray or GPU array or None

bcstep

Flag indicating whether to save the beam current.

TYPE: bool

xp

Numerical backend (e.g., numpy or cupy).

TYPE: module

RETURNS DESCRIPTION
None

print_recon_state

Display current reconstruction progress including loss, optimization state, and updates.

PARAMETER DESCRIPTION
t0

Start time of the epoch (Unix timestamp).

TYPE: float

algorithm

Name of the loss or optimization algorithm used.

TYPE: str

epoch

Current training epoch.

TYPE: int

current_loss

Loss value at current epoch.

TYPE: float

current_sse

Sum of squared errors.

TYPE: float

current_obj_step

Whether the object is being updated.

TYPE: bool

current_probe_step

Whether the probe is being updated.

TYPE: bool

current_probe_pos_step

Whether the scan grid is being updated.

TYPE: bool

current_tilts_step

Whether tilt corrections are being updated.

TYPE: bool

current_static_background_step

Whether static background is being updated.

TYPE: bool

current_aberrations_array_step

Whether aberration coefficients are being updated.

TYPE: bool

current_beam_current_step

Whether beam current is being updated.

TYPE: bool

current_hist_length

Optimizer memory length (0=GD, 1=CG, >1=BFGS).

TYPE: int

print_flag

Verbosity flag: 0 = silent, 1 = single-line print, 2 = verbose.

TYPE: int

RETURNS DESCRIPTION
None

try_to_gpu

Convert all key reconstruction variables to GPU arrays if using CuPy.

PARAMETER DESCRIPTION
obj

Object array.

TYPE: ndarray

probe

Probe array.

TYPE: ndarray

positions

Integer scan positions.

TYPE: ndarray

full_pos_correction

Sub-pixel scan grid correction.

TYPE: ndarray

tilts

Tilt values.

TYPE: ndarray

tilts_correction

Tilt corrections.

TYPE: ndarray

masks

Optional segmentation or region masks.

TYPE: ndarray or None

defocus_array

Array of defocus values per position.

TYPE: ndarray

slice_distances

Slice spacing in multislice simulations.

TYPE: ndarray

aperture_mask

Probe aperture mask.

TYPE: ndarray or None

dataset

Measured dataset.

TYPE: ndarray

load_one_by_one

Whether dataset is streamed from disk.

TYPE: bool

static_background

Static background array.

TYPE: ndarray or None

aberrations_array

Array of aberration coefficients.

TYPE: ndarray or None

beam_current

Beam current scaling factor.

TYPE: ndarray or None

default_float

Float precision dtype for casting.

TYPE: dtype

default_complex

Complex precision dtype for casting.

TYPE: dtype

default_int

Integer dtype for casting.

TYPE: dtype

xp

Numerical backend (numpy or cupy).

TYPE: module

RETURNS DESCRIPTION
tuple

The same variables in GPU format (if using CuPy), with proper types.

try_to_initialize_beam_current

Initialize beam current array or pad if it's too short.

PARAMETER DESCRIPTION
beam_current

Existing beam current values.

TYPE: ndarray or None

measured_data_shape

Shape of measured dataset.

TYPE: tuple

default_float

Float type for the array.

TYPE: dtype

xp

NumPy or CuPy.

TYPE: module

RETURNS DESCRIPTION
ndarray

Initialized or padded beam current.

get_value_for_epoch

Evaluate a list of values or functions at the current epoch.

PARAMETER DESCRIPTION
func_or_value

List of fixed values or callables.

TYPE: list

epoch

Current epoch number.

TYPE: int

default_float

Float precision type.

TYPE: dtype

RETURNS DESCRIPTION
list

Evaluated values.

get_steps_epoch

Evaluate step values for the current epoch.

PARAMETER DESCRIPTION
steps

List of (multiplier, callable) or fixed values.

TYPE: list

epoch

Current training epoch.

TYPE: int

default_float

Float precision type.

TYPE: dtype

RETURNS DESCRIPTION
list

List of step values.

lambda_to_string

Extract lambda function source as a string.

PARAMETER DESCRIPTION
f

Lambda function.

TYPE: function

RETURNS DESCRIPTION
str

Extracted string source of the lambda.

convert_to_string

Convert parameter dictionary to string format, including lambda serialization.

PARAMETER DESCRIPTION
dicti2

Original parameter dictionary.

TYPE: dict

strip_dataset_from_params

Whether to exclude 'dataset' key (default is True).

TYPE: bool DEFAULT: True

RETURNS DESCRIPTION
dict

Dictionary with string values.

string_to_lambda

Convert stringified lambda expression to a Python function.

PARAMETER DESCRIPTION
lambda_string

Lambda string to evaluate.

TYPE: str

RETURNS DESCRIPTION
callable or str

The resulting function or original string if evaluation fails.

load_params

Load parameter dictionary from a .pkl file.

PARAMETER DESCRIPTION
path

Path to the .pkl parameter file.

TYPE: str

RETURNS DESCRIPTION
dict

Loaded parameters.

string_params_to_usefull_params

Convert string-encoded lambdas in parameter dictionary back to callables.

PARAMETER DESCRIPTION
params

Parameter dictionary possibly containing lambda strings.

TYPE: dict

RETURNS DESCRIPTION
dict

Updated dictionary with callables.

save_params

Save parameters to a .pkl file, optionally removing the dataset.

PARAMETER DESCRIPTION
params_path

Output path for the parameter file.

TYPE: str

params

Parameter dictionary to save.

TYPE: dict

strip_dataset_from_params

If True, remove the dataset entry.

TYPE: bool

RETURNS DESCRIPTION
None

phase_cross_corr_align

Align two FFT-transformed images using phase cross-correlation.

PARAMETER DESCRIPTION
im_ref_fft

Reference image FFT.

TYPE: ndarray

im_2_fft

FFT of the image to be aligned.

TYPE: ndarray

refine_box_dim

Size of the interpolation box for sub-pixel alignment.

TYPE: int

upsample

Upsampling factor for interpolation.

TYPE: int

x_real

Real space x grid.

TYPE: ndarray

y_real

Real space y grid.

TYPE: ndarray

shift_y

Predefined shift in y (optional).

TYPE: float or None DEFAULT: None

shift_x

Predefined shift in x (optional).

TYPE: float or None DEFAULT: None

RETURNS DESCRIPTION
ndarray

Shifted FFT of the second image.

get_cupy_memory_usage

Print current CuPy GPU memory usage statistics.

RETURNS DESCRIPTION
None

get_compute_batch

Estimate the optimal compute batch size based on GPU memory usage.

PARAMETER DESCRIPTION
compute_batch

Initial guess or default.

TYPE: int

load_one_by_one

Whether data is streamed instead of fully loaded.

TYPE: bool

hist_size

History size for optimizers.

TYPE: int

measured_data_shape

Shape of the input dataset.

TYPE: tuple

memory_saturation

Proportion of GPU memory to use.

TYPE: float

smart_memory

User-provided memory strategy.

TYPE: callable or bool

data_pad

Padding applied to data.

TYPE: int

obj_shape

Shape of the object array.

TYPE: tuple

probe_shape

Shape of the probe array.

TYPE: tuple

dtype

Data type string ('single' or 'double').

TYPE: str

propmethod

Propagation method name.

TYPE: str

print_flag

Verbosity.

TYPE: int

RETURNS DESCRIPTION
tuple

Suggested batch size, load_one_by_one flag, and memory strategy.

load_nexus_params

Load reconstruction parameters from a NeXus (.nxs) HDF5 file.

PARAMETER DESCRIPTION
path_nexus

Path to the .nxs file.

TYPE: str

RETURNS DESCRIPTION
dict

Dictionary of extracted parameters.

delete_dataset_from_params

Delete the 'dataset' key from saved parameter file.

PARAMETER DESCRIPTION
params_path

Path to the pickled parameters file.

TYPE: str

RETURNS DESCRIPTION
None

convert_to_nxs

Convert saved PyPty reconstruction data to NeXus (.nxs) format.

PARAMETER DESCRIPTION
folder_path

Directory containing saved reconstruction files.

TYPE: str

output_file

Path where the NeXus file will be saved.

TYPE: str

RETURNS DESCRIPTION
None

pypty.vaa - PyPty (python + ptychography)

pypty.vaa

plot_modes

Plot the modes of a tensor.

PARAMETER DESCRIPTION
ttt

A 3D or 4D array containing the modes to be plotted.

TYPE: ndarray

fit_aberrations_to_wave

Calculate model positions based on step size and angle.

PARAMETER DESCRIPTION
wave

complex real-space wave

TYPE: ndarray

px_size_A

acc_voltage

thresh

DEFAULT: 0

aberrations_guess

DEFAULT: [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0]

plot

DEFAULT: True

ftol

DEFAULT: 1e-20

xtol

DEFAULT: 1e-20

loss

DEFAULT: 'linear'

max_mrad

DEFAULT: inf

RETURNS DESCRIPTION
list

list of fitted aberrations (in Angstrom)

mesh_model_positions

Calculate model positions based on step size and angle.

PARAMETER DESCRIPTION
step_size

The step size for the model.

TYPE: float

angle_rad

The angle in radians.

TYPE: float

x

The x coordinates.

TYPE: ndarray

y

The y coordinates.

TYPE: ndarray

RETURNS DESCRIPTION
tuple

The model x and y coordinates.

mesh_objective_positions

Objective function for mesh optimization.

PARAMETER DESCRIPTION
ini_guess

Initial guess for the optimization.

TYPE: list

x

The x coordinates.

TYPE: ndarray

y

The y coordinates.

TYPE: ndarray

mesh_x

The mesh x coordinates.

TYPE: ndarray

mesh_y

The mesh y coordinates.

TYPE: ndarray

RETURNS DESCRIPTION
float

The sum of squared differences.

get_step_angle_scan_grid

Determine the step size and angle for a scan grid.

PARAMETER DESCRIPTION
positions

The measured positions.

TYPE: ndarray

scan_size

The size of the scan grid.

TYPE: tuple

RETURNS DESCRIPTION
tuple

The step size and angle in degrees.

get_affine_tranform

Calculate the affine transformation matrix from positions.

PARAMETER DESCRIPTION
positions

The measured positions.

TYPE: ndarray

scan_size

The size of the scan grid.

TYPE: tuple

px_size_A

Pixel size in angstroms.

TYPE: float

RETURNS DESCRIPTION
ndarray

The deformation matrix.

add_scalebar_ax

Add a scale bar to a given axis.

PARAMETER DESCRIPTION
ax

The axes to which the scale bar will be added.

TYPE: Axes

x

The x-coordinate of the bottom left corner of the scale bar.

TYPE: float

y

The y-coordinate of the bottom left corner of the scale bar.

TYPE: float

width

The width of the scale bar in pixels.

TYPE: float

height

The height of the scale bar in pixels.

TYPE: float

x_t

The x-coordinate for the text label.

TYPE: float

y_t

The y-coordinate for the text label.

TYPE: float

px_size

The pixel size in the same units as the width and height.

TYPE: float

unit

The unit of measurement for the scale bar.

TYPE: str

outputlog_plots

Plot log file data from PyPty.

PARAMETER DESCRIPTION
loss_path

Path to the PyPty CSV file.

TYPE: str

skip_first

Number of initial iterations to skip (default is 0).

TYPE: int DEFAULT: 0

plot_time

If True, a second x-axis showing time in seconds will be added on top of the plot.

TYPE: bool DEFAULT: True

RETURNS DESCRIPTION
list

List of plotted figures.

radial_average

Calculate the radial average of a 2D array.

PARAMETER DESCRIPTION
ff

The input 2D array.

TYPE: ndarray

r_bins

The bin size for the radial average.

TYPE: float

r_max

The maximum radius for averaging.

TYPE: float

r_min

The minimum radius for averaging.

TYPE: float

px_size_A

Pixel size in angstroms.

TYPE: float

plot

If True, the radial average will be plotted (default is True).

TYPE: bool DEFAULT: True

RETURNS DESCRIPTION
Figure

The figure containing the plot if plot is True.

complex_pca

Perform PCA on complex data.

PARAMETER DESCRIPTION
data

The input data array of shape (N_y, N_x, N_obs).

TYPE: ndarray

n_components

The number of principal components to retain.

TYPE: int

RETURNS DESCRIPTION
ndarray

The reduced data array of shape (N_y, N_x, n_components).

complex_array_to_rgb

Convert a complex array to RGB format.

PARAMETER DESCRIPTION
X

The input array of complex numbers.

TYPE: ndarray

theme

The color theme, either 'dark' or 'light' (default is 'dark').

TYPE: str DEFAULT: 'dark'

rmax

Maximum absolute value for normalization (default is None).

TYPE: float DEFAULT: None

RETURNS DESCRIPTION
ndarray

The RGB representation of the input array.

plot_complex_modes

Plot complex modes in RGB format.

PARAMETER DESCRIPTION
p

The input array of complex modes.

TYPE: ndarray

nm

The number of modes to plot.

TYPE: int

sub

The number of rows for the subplot layout.

TYPE: int

RETURNS DESCRIPTION
Figure

The figure containing the plotted complex modes.